{ "swagger": "2.0", "info": { "description": "多因素认证服务，提供TOTP、短信验证码、邮件验证、推送通知等多种MFA方式", "title": "MFA Service API", "contact": {}, "version": "1.0.0" }, "basePath": "/api/v1", "paths": { "/admin/mfa/backup-codes": { "get": { "security": [ { "bearerAuth": [] } ], "description": "管理员查看租户下所有已配置TOTP备用恢复码的用户列表。参考：OWASP ASVS V2.8.3。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "管理端列出所有备用码配置", "responses": { "200": { "description": "备用码配置列表", "schema": { "$ref": "#/definitions/dto.AdminBackupCodesListResponse" } }, "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/backup-codes/{user_id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "管理员查看指定用户的备用恢复码数量。参考：OWASP ASVS V2.8.3。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "管理端获取用户备用码数量", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true } ], "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" } }, "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/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" } } } } }, "/admin/mfa/totp/{user_id}": { "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": "path", "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" } }, "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" } } } } }, "/internal/schedulers": { "get": { "description": "返回当前服务中所有注册的定时任务及其状态", "produces": [ "application/json" ], "tags": [ "系统" ], "summary": "列出所有定时任务", "responses": { "200": { "description": "调度器列表", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "400": { "description": "请求参数错误", "schema": { "$ref": "#/definitions/dto.Problem" } }, "401": { "description": "未认证或令牌无效", "schema": { "$ref": "#/definitions/dto.Problem" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/dto.Problem" } } } } }, "/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/register": { "post": { "security": [ { "bearerAuth": [] } ], "description": "生成 WebAuthn credential creation options (challenge, rp, user, pubKeyCredParams)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "开始WebAuthn凭证注册", "parameters": [ { "description": "开始注册请求 (可选 display_name)", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.BeginWebAuthnRegistrationRequest" } } ], "responses": { "200": { "description": "credentialCreationOptions", "schema": { "$ref": "#/definitions/dto.DataResponse-protocol_CredentialCreation" } }, "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/register/verify": { "post": { "security": [ { "bearerAuth": [] } ], "description": "验证 attestation 响应并存储凭证。需要先调用 /mfa/webauthn/credentials/register 获取 creation options。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "完成WebAuthn凭证注册", "parameters": [ { "description": "注册完成请求 (credential response)", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.FinishWebAuthnRegistrationRequest" } } ], "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" } }, "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.AdminBackupCodesListItem": { "type": "object", "properties": { "count": { "type": "integer", "example": 8 }, "user_id": { "type": "string", "example": "user-abc123" } } }, "dto.AdminBackupCodesListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.AdminBackupCodesListItem" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "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.BeginWebAuthnRegistrationRequest": { "type": "object", "properties": { "display_name": { "type": "string" } } }, "dto.CreateIPWhitelistRequest": { "type": "object", "required": [ "cidr", "label" ], "properties": { "cidr": { "type": "string", "example": "192.168.1.0/24" }, "label": { "type": "string", "example": "office network" } } }, "dto.DataResponse-protocol_CredentialCreation": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/protocol.CredentialCreation" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "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" }, "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": { "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.FieldViolation": { "type": "object", "properties": { "code": { "description": "Code 是错误代码（可选）\n用于程序识别错误类型，如 \"required\", \"format\", \"range\"", "type": "string" }, "description": { "description": "Description 是人类可读的错误描述\n应该说明违反了什么规则，如 \"必须是一个有效的邮箱地址\"", "type": "string" }, "field": { "description": "Field 是错误字段的路径\n使用点号表示嵌套字段，如 \"user.email\" 或 \"addresses[0].city\"", "type": "string" }, "value": { "description": "Value 是导致错误的值（可选，开发模式下使用）\n生产环境可能不返回此字段以避免泄露敏感信息" } } }, "dto.FinishWebAuthnRegistrationRequest": { "type": "object", "required": [ "id", "raw_id", "response", "type" ], "properties": { "id": { "type": "string" }, "raw_id": { "type": "string" }, "response": { "type": "object", "required": [ "attestation_object", "client_data_json" ], "properties": { "attestation_object": { "type": "string" }, "client_data_json": { "type": "string" }, "transports": { "type": "array", "items": { "type": "string" } } } }, "type": { "type": "string" } } }, "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.Problem": { "type": "object", "properties": { "code": { "description": "Code 是业务错误码\n用于程序处理特定错误场景\n示例：30101001", "type": "integer" }, "detail": { "description": "Detail 是针对此具体错误实例的人类可读解释\n可以包含具体的错误细节，如\"Field 'email' is required\"", "type": "string" }, "errors": { "description": "Errors 是字段级验证错误列表（扩展字段）\n遵循 Web API 标准实践，每个错误包含字段名和错误信息", "type": "array", "items": { "$ref": "#/definitions/dto.FieldViolation" } }, "i18n_args": { "description": "I18nArgs 是国际化参数\n用于动态填充翻译模板", "type": "object", "additionalProperties": {} }, "i18n_key": { "description": "I18nKey 是国际化键\n用于客户端本地化错误消息\n示例：\"error.user_not_found\"", "type": "string" }, "instance": { "description": "Instance 是发生问题的具体URI引用\n通常是请求的URL，可能包含查询参数\n示例：\"/api/v1/users?limit=invalid\"", "type": "string" }, "request_id": { "description": "RequestID 是请求唯一标识\n用于日志关联和问题追踪\n示例：\"req_550e8400-e29b-41d4-a716-446655440000\"", "type": "string" }, "retry_after": { "description": "RetryAfter 用于 429 Too Many Requests 响应\n指示客户端应在多少秒后重试请求（RFC 6585）", "type": "integer" }, "service": { "description": "Service 是服务名\n用于微服务架构中定位错误来源\n示例：\"auth-service\"", "type": "string" }, "span_id": { "description": "SpanID 是当前 span 标识\n用于精确定位分布式链路中的当前节点", "type": "string" }, "status": { "description": "Status 是产生的HTTP状态码\n用于客户端区分问题类型，不随Accept-Language变化\n示例：400, 401, 403, 404, 500", "type": "integer" }, "timestamp": { "description": "Timestamp 是错误发生时间\nISO 8601 格式\n示例：\"2026-04-03T12:00:00Z\"", "type": "string" }, "title": { "description": "Title 是简短、人类可读的问题类型摘要\n相同的 Type 应该始终有相同的 Title（不随实例变化）\n示例：\"Invalid Request Parameters\"", "type": "string" }, "trace_id": { "description": "TraceID 是分布式追踪标识\n遵循 W3C Trace Context 标准\n示例：\"00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01\"", "type": "string" }, "type": { "description": "Type 是标识问题类型的URI引用\n当该URI被解引用时，应提供人类可读的文档\n示例：\"https://api.example.com/errors/invalid-request\"", "type": "string" } } }, "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": { "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" } } }, "protocol.AttestationFormat": { "type": "string", "enum": [ "packed", "tpm", "android-key", "android-safetynet", "fido-u2f", "apple", "compound", "none" ], "x-enum-varnames": [ "AttestationFormatPacked", "AttestationFormatTPM", "AttestationFormatAndroidKey", "AttestationFormatAndroidSafetyNet", "AttestationFormatFIDOUniversalSecondFactor", "AttestationFormatApple", "AttestationFormatCompound", "AttestationFormatNone" ] }, "protocol.AuthenticationExtensions": { "type": "object", "additionalProperties": {} }, "protocol.AuthenticatorAttachment": { "type": "string", "enum": [ "platform", "cross-platform" ], "x-enum-varnames": [ "Platform", "CrossPlatform" ] }, "protocol.AuthenticatorSelection": { "type": "object", "properties": { "authenticatorAttachment": { "description": "AuthenticatorAttachment If this member is present, eligible authenticators are filtered to only\nauthenticators attached with the specified AuthenticatorAttachment enum.", "allOf": [ { "$ref": "#/definitions/protocol.AuthenticatorAttachment" } ] }, "requireResidentKey": { "description": "RequireResidentKey this member describes the Relying Party's requirements regarding resident\ncredentials. If the parameter is set to true, the authenticator MUST create a client-side-resident\npublic key credential source when creating a public key credential.", "type": "boolean" }, "residentKey": { "description": "ResidentKey this member describes the Relying Party's requirements regarding resident\ncredentials per Webauthn Level 2.", "allOf": [ { "$ref": "#/definitions/protocol.ResidentKeyRequirement" } ] }, "userVerification": { "description": "UserVerification This member describes the Relying Party's requirements regarding user verification for\nthe create() operation. Eligible authenticators are filtered to only those capable of satisfying this\nrequirement.", "allOf": [ { "$ref": "#/definitions/protocol.UserVerificationRequirement" } ] } } }, "protocol.AuthenticatorTransport": { "type": "string", "enum": [ "usb", "nfc", "ble", "smart-card", "hybrid", "internal" ], "x-enum-varnames": [ "USB", "NFC", "BLE", "SmartCard", "Hybrid", "Internal" ] }, "protocol.ConveyancePreference": { "type": "string", "enum": [ "none", "indirect", "direct", "enterprise" ], "x-enum-varnames": [ "PreferNoAttestation", "PreferIndirectAttestation", "PreferDirectAttestation", "PreferEnterpriseAttestation" ] }, "protocol.CredentialCreation": { "type": "object", "properties": { "mediation": { "$ref": "#/definitions/protocol.CredentialMediationRequirement" }, "publicKey": { "$ref": "#/definitions/protocol.PublicKeyCredentialCreationOptions" } } }, "protocol.CredentialDescriptor": { "type": "object", "properties": { "id": { "description": "CredentialID The ID of a credential to allow/disallow.", "type": "array", "items": { "type": "integer" } }, "transports": { "description": "The authenticator transports that can be used.", "type": "array", "items": { "$ref": "#/definitions/protocol.AuthenticatorTransport" } }, "type": { "description": "The valid credential types.", "allOf": [ { "$ref": "#/definitions/protocol.CredentialType" } ] } } }, "protocol.CredentialMediationRequirement": { "type": "string", "enum": [ "", "silent", "optional", "conditional", "required" ], "x-enum-varnames": [ "MediationDefault", "MediationSilent", "MediationOptional", "MediationConditional", "MediationRequired" ] }, "protocol.CredentialParameter": { "type": "object", "properties": { "alg": { "$ref": "#/definitions/webauthncose.COSEAlgorithmIdentifier" }, "type": { "$ref": "#/definitions/protocol.CredentialType" } } }, "protocol.CredentialType": { "type": "string", "enum": [ "public-key" ], "x-enum-varnames": [ "PublicKeyCredentialType" ] }, "protocol.PublicKeyCredentialCreationOptions": { "type": "object", "properties": { "attestation": { "$ref": "#/definitions/protocol.ConveyancePreference" }, "attestationFormats": { "type": "array", "items": { "$ref": "#/definitions/protocol.AttestationFormat" } }, "authenticatorSelection": { "$ref": "#/definitions/protocol.AuthenticatorSelection" }, "challenge": { "type": "array", "items": { "type": "integer" } }, "excludeCredentials": { "type": "array", "items": { "$ref": "#/definitions/protocol.CredentialDescriptor" } }, "extensions": { "$ref": "#/definitions/protocol.AuthenticationExtensions" }, "hints": { "type": "array", "items": { "$ref": "#/definitions/protocol.PublicKeyCredentialHints" } }, "pubKeyCredParams": { "type": "array", "items": { "$ref": "#/definitions/protocol.CredentialParameter" } }, "rp": { "$ref": "#/definitions/protocol.RelyingPartyEntity" }, "timeout": { "type": "integer" }, "user": { "$ref": "#/definitions/protocol.UserEntity" } } }, "protocol.PublicKeyCredentialHints": { "type": "string", "enum": [ "security-key", "client-device", "hybrid" ], "x-enum-varnames": [ "PublicKeyCredentialHintSecurityKey", "PublicKeyCredentialHintClientDevice", "PublicKeyCredentialHintHybrid" ] }, "protocol.RelyingPartyEntity": { "type": "object", "properties": { "id": { "description": "A unique identifier for the Relying Party entity, which sets the RP ID.", "type": "string" }, "name": { "description": "A human-palatable name for the entity. Its function depends on what the PublicKeyCredentialEntity represents:\n\nWhen inherited by PublicKeyCredentialRpEntity it is a human-palatable identifier for the Relying Party,\nintended only for display. For example, \"ACME Corporation\", \"Wonderful Widgets, Inc.\" or \"ОАО Примертех\".\n\nWhen inherited by PublicKeyCredentialUserEntity, it is a human-palatable identifier for a user account. It is\nintended only for display, i.e., aiding the user in determining the difference between user accounts with similar\ndisplayNames. For example, \"alexm\", \"alex.p.mueller@example.com\" or \"+14255551234\".", "type": "string" } } }, "protocol.ResidentKeyRequirement": { "type": "string", "enum": [ "discouraged", "preferred", "required" ], "x-enum-varnames": [ "ResidentKeyRequirementDiscouraged", "ResidentKeyRequirementPreferred", "ResidentKeyRequirementRequired" ] }, "protocol.UserEntity": { "type": "object", "properties": { "displayName": { "description": "A human-palatable name for the user account, intended only for display.\nFor example, \"Alex P. Müller\" or \"田中 倫\". The Relying Party SHOULD let\nthe user choose this, and SHOULD NOT restrict the choice more than necessary.", "type": "string" }, "id": { "description": "ID is the user handle of the user account entity. To ensure secure operation,\nauthentication and authorization decisions MUST be made on the basis of this id\nmember, not the displayName nor name members. See Section 6.1 of\n[RFC8266](https://www.w3.org/TR/webauthn/#biblio-rfc8266)." }, "name": { "description": "A human-palatable name for the entity. Its function depends on what the PublicKeyCredentialEntity represents:\n\nWhen inherited by PublicKeyCredentialRpEntity it is a human-palatable identifier for the Relying Party,\nintended only for display. For example, \"ACME Corporation\", \"Wonderful Widgets, Inc.\" or \"ОАО Примертех\".\n\nWhen inherited by PublicKeyCredentialUserEntity, it is a human-palatable identifier for a user account. It is\nintended only for display, i.e., aiding the user in determining the difference between user accounts with similar\ndisplayNames. For example, \"alexm\", \"alex.p.mueller@example.com\" or \"+14255551234\".", "type": "string" } } }, "protocol.UserVerificationRequirement": { "type": "string", "enum": [ "required", "preferred", "discouraged" ], "x-enum-comments": { "VerificationPreferred": "This is the default." }, "x-enum-varnames": [ "VerificationRequired", "VerificationPreferred", "VerificationDiscouraged" ] }, "webauthncose.COSEAlgorithmIdentifier": { "type": "integer", "enum": [ -7, -8, -9, -19, -35, -36, -37, -38, -39, -47, -48, -49, -50, -51, -52, -257, -258, -259, -65535 ], "x-enum-varnames": [ "AlgES256", "AlgEdDSA", "AlgESP256", "AlgEd25519", "AlgES384", "AlgES512", "AlgPS256", "AlgPS384", "AlgPS512", "AlgES256K", "AlgMLDSA44", "AlgMLDSA65", "AlgMLDSA87", "AlgESP384", "AlgESP512", "AlgRS256", "AlgRS384", "AlgRS512", "AlgRS1" ] } }, "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" } ] }