Core：登录、会话与账户安全

当前固定源码下本组共 48 项方法 + 路径。下列为接口需求 v0.1，Owner 为 Core，计划阶段为 CE-02；均未宣称 OceanWay 已运行。原路径/字段默认沿用，变化须进入差异台账。

每项适用统一接口需求规则，并列出上游字段声明、控制器观察与具体补差。OpenAPI 没列必填不表示运行时可缺省；观察到的 JSON key 也不等于可写入字段。下载完整接口台账及上游管理规范、模型规范可查看完整嵌套 Schema。

CORE-AUTH-001 · GET /api/oauth/:provider

用途与归属：HandleOAuth。优先沿用，迁入/适配后验收。

鉴权：可选客户身份，匿名行为按处理器与配置；处理器安全证明用途：VerificationScopeAccountBind。

请求：Path：provider（必填；以实际路由名为准）。处理器读取：path.provider, query.state, query.error, query.error_description, query.code。自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。

返回：上游 OpenAPI 无本项响应规范；按处理器返回值补齐成功、拒绝和错误结构；代码 JSON/映射中观察到 message, notification_failed, provider, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

业务与副作用：签发、刷新、撤销与设备/二次验证必须保持上游生命周期；登录失败不能泄漏账户存在性或凭据。退出/撤销后按声明时限失效；跨子站 SSO 属新增差异，不把已有 OAuth 登录当授权服务器。

幂等、重试与异常：读取可有界重试，不新建调用或扣款；结果为空、权限失败与查询未知分开。保留原 HTTP 状态、业务 success/message 或模型 error 包络，不将所有失败改成同一状态。区分参数、身份、权限、余额、限流、上游与执行未知；敏感栈和供应凭据不返回客户。

验收需求：成功与空态；缺失/非法字段；未登录/跨账户/无权限；限流；资源不存在；重试与状态冲突；数据库提交后响应丢失（写操作）；返回字段与既有协议兼容。

迁入差异：OPENAPI-MISSING：源码已注册，上游 OpenAPI 无匹配操作。

来源：router/api-router.go:59；controller.HandleOAuth controller/oauth.go:146。

CORE-AUTH-002 · POST /api/oauth/email/bind

用途与归属：绑定邮箱。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）。

请求：Body 字段（application/json）：email:string [规范声明必填] format="email"; code:string [规范声明必填]。

返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 data, message, notification_failed, notification_warning, provider, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

幂等、重试与异常：沿用原行为，不擅自要求所有旧接口新增 Idempotency-Key；创建/财务动作必须定义重复点击和响应丢失结果，客户端不得无条件自动重试。保留原 HTTP 状态、业务 success/message 或模型 error 包络，不将所有失败改成同一状态。区分参数、身份、权限、余额、限流、上游与执行未知；敏感栈和供应凭据不返回客户。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:51；controller.EmailBind controller/email_binding.go:82；上游 api.json 中 POST /api/oauth/email/bind。

CORE-AUTH-003 · POST /api/oauth/email/bind/resend

用途与归属：EmailBindResend。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）。

请求：Body 类型：controller.emailBindRequest controller/email_binding.go:13；允许写入字段按处理器白名单，不把整个数据库结构直接开放。

返回：上游 OpenAPI 无本项响应规范；按处理器返回值补齐成功、拒绝和错误结构；处理器使用 common.ApiSuccess 包络；代码 JSON/映射中观察到 success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：OPENAPI-MISSING：源码已注册，上游 OpenAPI 无匹配操作。

来源：router/api-router.go:50；controller.EmailBindResend controller/email_binding.go:58。

CORE-AUTH-004 · POST /api/oauth/email/bind/start

用途与归属：EmailBindStart。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）；处理器安全证明用途：VerificationScopeAccountBind。

请求：Body 类型：controller.emailBindRequest controller/email_binding.go:13；允许写入字段按处理器白名单，不把整个数据库结构直接开放。

返回：上游 OpenAPI 无本项响应规范；按处理器返回值补齐成功、拒绝和错误结构；处理器使用 common.ApiSuccess 包络；代码 JSON/映射中观察到 notification_failed, provider, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：OPENAPI-MISSING：源码已注册，上游 OpenAPI 无匹配操作。

来源：router/api-router.go:49；controller.EmailBindStart controller/email_binding.go:20。

CORE-AUTH-005 · POST /api/oauth/state

用途与归属：生成OAuth State。优先沿用，迁入/适配后验收。

鉴权：可选客户身份，匿名行为按处理器与配置；处理器安全证明用途：VerificationScopeAccountBind。

请求：Body 字段（application/json）：provider:string [规范声明必填]; intent:string [规范声明必填] enum=["login", "bind"]; aff:string [规范未列必填]。

返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 data, expires_at, flow_token, message, provider, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:48；controller.GenerateOAuthCode controller/oauth.go:46；上游 api.json 中 POST /api/oauth/state。

CORE-AUTH-006 · GET /api/oauth/telegram/bind/:flow_token

用途与归属：完成 Telegram 绑定。优先沿用，迁入/适配后验收。

鉴权：未挂 User/Admin/Token 认证；按处理器及配置校验。

请求：Path：flow_token（必填；以实际路由名为准）。OpenAPI 参数：path.flow_token:string（必填）。自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。

返回：302 重定向到 /oauth/telegram 的绑定结果回调（上游未声明响应 Schema）；代码 JSON/映射中观察到 code, message, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:57；controller.TelegramLegacyAuth controller/telegram.go:11；上游 api.json 中 GET /api/oauth/telegram/bind/{flow_token}。

CORE-AUTH-007 · POST /api/oauth/telegram/bind/start

用途与归属：创建 Telegram 绑定流程。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）。

请求：Body/表单由下方处理器定义；上游未提供完整 Schema，本项要求迁入时补出字段白名单、必填、类型、默认和限制，缺失不作为“任意 JSON”开放。

返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 code, message, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:56；controller.TelegramLegacyAuth controller/telegram.go:11；上游 api.json 中 POST /api/oauth/telegram/bind/start。

CORE-AUTH-008 · GET /api/oauth/telegram/login

用途与归属：Telegram登录。优先沿用，迁入/适配后验收。

鉴权：未挂 User/Admin/Token 认证；按处理器及配置校验。

请求：自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。

返回：200 成功（上游未声明响应 Schema）；409 （上游未声明响应 Schema）；429 （上游未声明响应 Schema）；代码 JSON/映射中观察到 code, message, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐；AUTH-DOC-CONFLICT：登录 OpenAPI 的 security 与路由用途不一致，以真实处理器链为准。

来源：router/api-router.go:55；controller.TelegramLegacyAuth controller/telegram.go:11；上游 api.json 中 GET /api/oauth/telegram/login。

CORE-AUTH-009 · GET /api/oauth/wechat

用途与归属：微信OAuth登录。优先沿用，迁入/适配后验收。

鉴权：未挂 User/Admin/Token 认证；按处理器及配置校验。

请求：处理器读取：query.code。自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。

返回：200 成功（上游未声明响应 Schema）；409 （上游未声明响应 Schema）；429 （上游未声明响应 Schema）；代码 JSON/映射中观察到 message, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:53；controller.WeChatAuth controller/wechat.go:58；上游 api.json 中 GET /api/oauth/wechat。

CORE-AUTH-010 · POST /api/oauth/wechat/bind

用途与归属：绑定微信。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）；处理器安全证明用途：VerificationScopeAccountBind。

请求：Body 字段（application/json）：code:string [规范声明必填]。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:54；controller.WeChatBind controller/wechat.go:131；上游 api.json 中 POST /api/oauth/wechat/bind。

CORE-AUTH-011 · GET /api/reset_password

用途与归属：发送密码重置邮件。优先沿用，迁入/适配后验收。

鉴权：未挂 User/Admin/Token 认证；按处理器及配置校验。

请求：OpenAPI 参数：query.email:string（必填）。处理器读取：query.email。自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。

返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 message, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

幂等、重试与异常：默认读取可重试；但上游存在 GET 执行动作/签发凭据，必须按处理器确认。不得把方法名作为安全重试的唯一依据。保留原 HTTP 状态、业务 success/message 或模型 error 包络，不将所有失败改成同一状态。区分参数、身份、权限、余额、限流、上游与执行未知；敏感栈和供应凭据不返回客户。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:45；controller.SendPasswordResetEmail controller/misc.go:248；上游 api.json 中 GET /api/reset_password。

CORE-AUTH-012 · POST /api/user/2fa/backup_codes

用途与归属：重新生成备用码。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）；处理器安全证明用途：VerificationScopeTwoFABackupCodes。

返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 data, message, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:133；controller.RegenerateBackupCodes controller/twofa.go:126；上游 api.json 中 POST /api/user/2fa/backup_codes。

CORE-AUTH-013 · POST /api/user/2fa/disable

用途与归属：禁用2FA。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）；处理器安全证明用途：VerificationScopeTwoFADisable。

请求：Body 字段（application/json）：code:string [规范未列必填]。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:132；controller.Disable2FA controller/twofa.go:63；上游 api.json 中 POST /api/user/2fa/disable。

CORE-AUTH-014 · POST /api/user/2fa/enable

用途与归属：启用2FA。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）。

请求：Body 字段（application/json）：code:string [规范未列必填]。

返回：200 成功（上游未声明响应 Schema）；处理器使用 common.ApiSuccess 包络。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:131；controller.Enable2FA controller/twofa.go:38；上游 api.json 中 POST /api/user/2fa/enable。

CORE-AUTH-015 · POST /api/user/2fa/setup

用途与归属：设置2FA。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）；处理器安全证明用途：VerificationScopeTwoFASetup。

返回：200 成功（上游未声明响应 Schema）；处理器使用 common.ApiSuccess 包络。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:130；controller.Setup2FA controller/twofa.go:23；上游 api.json 中 POST /api/user/2fa/setup。

CORE-AUTH-016 · GET /api/user/2fa/stats

用途与归属：获取2FA统计。优先沿用，迁入/适配后验收。

鉴权：Admin 员工身份。

请求：自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:162；controller.Admin2FAStats controller/twofa.go:176；上游 api.json 中 GET /api/user/2fa/stats。

CORE-AUTH-017 · GET /api/user/2fa/status

用途与归属：获取2FA状态。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）。

请求：自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。

返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 data, enabled, locked, message, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:129；controller.Get2FAStatus controller/twofa.go:90；上游 api.json 中 GET /api/user/2fa/status。

CORE-AUTH-018 · DELETE /api/user/:id/2fa

用途与归属：管理员禁用用户2FA。优先沿用，迁入/适配后验收。

鉴权：Admin 员工身份。

请求：Path：id（必填；以实际路由名为准）。OpenAPI 参数：path.id:integer（必填）。处理器读取：path.id。自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。

返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 message, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:163；controller.AdminDisable2FA controller/twofa.go:191；上游 api.json 中 DELETE /api/user/{id}/2fa。

CORE-AUTH-019 · DELETE /api/user/:id/bindings/:binding_type

用途与归属：AdminClearUserBinding。优先沿用，迁入/适配后验收。

鉴权：Admin 员工身份。

请求：Path：id, binding_type（必填；以实际路由名为准）。处理器读取：path.id, path.binding_type。自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。

返回：上游 OpenAPI 无本项响应规范；按处理器返回值补齐成功、拒绝和错误结构；代码 JSON/映射中观察到 bindingType, message, success, username（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：OPENAPI-MISSING：源码已注册，上游 OpenAPI 无匹配操作。

来源：router/api-router.go:153；controller.AdminClearUserBinding controller/user.go:718。

CORE-AUTH-020 · GET /api/user/:id/oauth/bindings

用途与归属：GetUserOAuthBindingsByAdmin。优先沿用，迁入/适配后验收。

鉴权：Admin 员工身份。

请求：Path：id（必填；以实际路由名为准）。处理器读取：path.id。自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。

返回：上游 OpenAPI 无本项响应规范；按处理器返回值补齐成功、拒绝和错误结构；代码 JSON/映射中观察到 data, message, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：OPENAPI-MISSING：源码已注册，上游 OpenAPI 无匹配操作。

来源：router/api-router.go:151；controller.GetUserOAuthBindingsByAdmin controller/custom_oauth.go:491。

CORE-AUTH-021 · DELETE /api/user/:id/oauth/bindings/:provider_id

用途与归属：UnbindCustomOAuthByAdmin。优先沿用，迁入/适配后验收。

鉴权：Admin 员工身份。

请求：Path：id, provider_id（必填；以实际路由名为准）。处理器读取：path.id, path.provider_id。自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。

返回：上游 OpenAPI 无本项响应规范；按处理器返回值补齐成功、拒绝和错误结构；代码 JSON/映射中观察到 message, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：OPENAPI-MISSING：源码已注册，上游 OpenAPI 无匹配操作。

来源：router/api-router.go:152；controller.UnbindCustomOAuthByAdmin controller/custom_oauth.go:570。

CORE-AUTH-022 · DELETE /api/user/:id/reset_passkey

用途与归属：管理员重置用户Passkey。优先沿用，迁入/适配后验收。

鉴权：Admin 员工身份。

返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 id, message, success, username（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:159；controller.AdminResetPasskey controller/passkey.go:443；上游 api.json 中 DELETE /api/user/{id}/reset_passkey。

CORE-AUTH-023 · POST /api/user/auth/logout

用途与归属：撤销当前登录会话。优先沿用，迁入/适配后验收。

鉴权：未挂 User/Admin/Token 认证；按处理器及配置校验；会话 Cookie 与 Origin 校验。

请求：OpenAPI 参数：header.X-Auth-Session:string。处理器读取：header.X-Auth-Session, header.Authorization。Refresh Cookie 或 Authorization 中有效访问凭据，X-Auth-Session 可指定预期 Session；无必填 JSON。

返回：success/message；访问令牌分支 data.revoked_sid 与 cookie_cleared；无 Cookie 分支清理后仍可成功。不能将退出一个 Session 当退出全部设备。

验收需求：退出当前 Session、Cookie 与预期 SID 冲突、访问令牌分支、无 Cookie 重复退出、其他设备不被误撤销。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:76；controller.AuthLogout controller/auth_session.go:47；上游 api.json 中 POST /api/user/auth/logout。

CORE-AUTH-024 · POST /api/user/auth/refresh

用途与归属：刷新面板登录。优先沿用，迁入/适配后验收。

鉴权：未挂 User/Admin/Token 认证；按处理器及配置校验；会话 Cookie 与 Origin 校验。

请求：OpenAPI 参数：header.X-Auth-Session:string。处理器读取：header.X-Auth-Session。Refresh Cookie 必需；X-Auth-Session 按原会话校验；无额外必填 JSON。保留 Cookie Origin Guard 与 NoStore。

返回：success/message/data；data.access_token、token_type、access_expires_at、user、session，写入轮换后的刷新 Cookie。无效或已撤销刷新令牌按原逻辑清 Cookie。

验收需求：正常刷新、缺 Cookie、无效/撤销、Session 不匹配、跨 Origin、轮换与过期，不泄漏刷新令牌到日志。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:75；controller.RefreshAuth controller/auth_session.go:17；上游 api.json 中 POST /api/user/auth/refresh。

CORE-AUTH-025 · POST /api/user/login

用途与归属：用户登录。优先沿用，迁入/适配后验收。

鉴权：未挂 User/Admin/Token 认证；按处理器及配置校验。

请求：JSON：username 必填；password 与 password_encrypted + encryption_key_id 按密码加密配置选择，启用加密时两项加密字段必需。验证码/二次验证沿用原登录流程。

返回：返回原登录成功/后续验证响应，设置并保护原会话凭据；409 AUTH_SESSION_LIMIT 与 429 AUTH_SESSION_ISSUANCE_LIMIT 不能显示为密码错误。

验收需求：普通/加密登录、缺少字段、错误密码、关闭密码登录、2FA 分支、会话上限、刷新后撤销。

迁入差异：AUTH-DOC-CONFLICT：登录 OpenAPI 的 security 与路由用途不一致，以真实处理器链为准。

来源：router/api-router.go:79；controller.Login controller/user.go:53；上游 api.json 中 POST /api/user/login。

CORE-AUTH-026 · POST /api/user/login/2fa

用途与归属：两步验证登录。优先沿用，迁入/适配后验收。

鉴权：未挂 User/Admin/Token 认证；按处理器及配置校验。

请求：Body 字段（application/json）：code:string [规范未列必填]; flow_token:string [规范未列必填]。

返回：200 成功（上游未声明响应 Schema）；409 该用户的活跃登录 Session 已达上限；内容类型 application/json；429 该用户在统计窗口内创建的 Session 已达上限；内容类型 application/json；409 application/json 字段：success:boolean [规范声明必填] enum=[false]; code:string [规范声明必填] enum=["AUTH_SESSION_LIMIT", "AUTH_SESSION_ISSUANCE_LIMIT"]; message:string [规范声明必填]；429 application/json 字段：success:boolean [规范声明必填] enum=[false]; code:string [规范声明必填] enum=["AUTH_SESSION_LIMIT", "AUTH_SESSION_ISSUANCE_LIMIT"]; message:string [规范声明必填]。

迁入差异：AUTH-DOC-CONFLICT：登录 OpenAPI 的 security 与路由用途不一致，以真实处理器链为准。

来源：router/api-router.go:80；controller.Verify2FALogin controller/twofa.go:171；上游 api.json 中 POST /api/user/login/2fa。

CORE-AUTH-027 · GET /api/user/login/encryption-key

用途与归属：GetPasswordEncryptionKey。优先沿用，迁入/适配后验收。

鉴权：未挂 User/Admin/Token 认证；按处理器及配置校验。

请求：自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。

返回：上游 OpenAPI 无本项响应规范；按处理器返回值补齐成功、拒绝和错误结构；处理器使用 common.ApiSuccess 包络；代码 JSON/映射中观察到 enabled, kid, public_key（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：OPENAPI-MISSING：源码已注册，上游 OpenAPI 无匹配操作。

来源：router/api-router.go:78；controller.GetPasswordEncryptionKey controller/user.go:36。

CORE-AUTH-028 · POST /api/user/login/passkey/begin

用途与归属：LoginPasskeyBegin。优先沿用，迁入/适配后验收。

鉴权：未挂 User/Admin/Token 认证；按处理器及配置校验。

请求：处理器匿名请求字段：flow_token:string（条件必填看处理器）, rp_id:string（条件必填看处理器）。

返回：上游 OpenAPI 无本项响应规范；按处理器返回值补齐成功、拒绝和错误结构；处理器使用 common.ApiSuccess 包络；代码 JSON/映射中观察到 expires_at, flow_token, options, rp_ids（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：OPENAPI-MISSING：源码已注册，上游 OpenAPI 无匹配操作。

来源：router/api-router.go:82；controller.LoginPasskeyBegin controller/login_verification.go:41。

CORE-AUTH-029 · POST /api/user/login/passkey/finish

用途与归属：LoginPasskeyFinish。优先沿用，迁入/适配后验收。

鉴权：未挂 User/Admin/Token 认证；按处理器及配置校验。

请求：处理器匿名请求字段：flow_token:string（条件必填看处理器）, passkey_flow_token:string（条件必填看处理器）, credential:json.RawMessage（条件必填看处理器）。

返回：上游 OpenAPI 无本项响应规范；按处理器返回值补齐成功、拒绝和错误结构。

迁入差异：OPENAPI-MISSING：源码已注册，上游 OpenAPI 无匹配操作。

来源：router/api-router.go:83；controller.LoginPasskeyFinish controller/login_verification.go:86。

CORE-AUTH-030 · POST /api/user/login/verify

用途与归属：VerifyLogin。优先沿用，迁入/适配后验收。

鉴权：未挂 User/Admin/Token 认证；按处理器及配置校验。

请求：JSON：flow_token、code 必填；method 缺省使用上游 2FA 方法且只接受对应方法。

返回：原二次验证成功响应与会话结果；过期/错用途 flow、错误验证码按原错误流程。

验收需求：缺字段、过期 flow、错误 code、非法 method、同 flow 重放与签发限制。

迁入差异：OPENAPI-MISSING：源码已注册，上游 OpenAPI 无匹配操作。

来源：router/api-router.go:81；controller.VerifyLogin controller/login_verification.go:16。

CORE-AUTH-031 · GET /api/user/oauth/bindings

用途与归属：GetUserOAuthBindings。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）。

请求：自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。

迁入差异：OPENAPI-MISSING：源码已注册，上游 OpenAPI 无匹配操作。

来源：router/api-router.go:140；controller.GetUserOAuthBindings controller/custom_oauth.go:471。

CORE-AUTH-032 · DELETE /api/user/oauth/bindings/:provider_id

用途与归属：UnbindCustomOAuth。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）；处理器安全证明用途：VerificationScopeAccountUnbind。

请求：Path：provider_id（必填；以实际路由名为准）。处理器读取：path.provider_id。自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。

返回：上游 OpenAPI 无本项响应规范；按处理器返回值补齐成功、拒绝和错误结构；代码 JSON/映射中观察到 data, message, notification_failed, notification_warning, provider_id, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：OPENAPI-MISSING：源码已注册，上游 OpenAPI 无匹配操作。

来源：router/api-router.go:141；controller.UnbindCustomOAuth controller/custom_oauth.go:525。

CORE-AUTH-033 · DELETE /api/user/passkey

用途与归属：删除Passkey。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）；处理器安全证明用途：VerificationScopePasskeyDelete。

请求：自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:111；controller.PasskeyDelete controller/passkey.go:216；上游 api.json 中 DELETE /api/user/passkey。

CORE-AUTH-034 · GET /api/user/passkey

用途与归属：获取Passkey状态。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）。

请求：自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。

返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 data, enabled, last_used_at, message, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:106；controller.PasskeyStatus controller/passkey.go:250；上游 api.json 中 GET /api/user/passkey。

CORE-AUTH-035 · POST /api/user/passkey/login/begin

用途与归属：开始Passkey登录。优先沿用，迁入/适配后验收。

鉴权：未挂 User/Admin/Token 认证；按处理器及配置校验。

请求：处理器匿名请求字段：rp_id:string（条件必填看处理器）。

返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 data, expires_at, flow_token, message, options, rp_ids, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

来源：router/api-router.go:84；controller.PasskeyLoginBegin controller/passkey.go:285；上游 api.json 中 POST /api/user/passkey/login/begin。

CORE-AUTH-036 · POST /api/user/passkey/login/finish

用途与归属：完成Passkey登录。优先沿用，迁入/适配后验收。

鉴权：未挂 User/Admin/Token 认证；按处理器及配置校验。

返回：200 成功（上游未声明响应 Schema）；409 该用户的活跃登录 Session 已达上限；内容类型 application/json；429 该用户在统计窗口内创建的 Session 已达上限；内容类型 application/json；代码 JSON/映射中观察到 message, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）；409 application/json 字段：success:boolean [规范声明必填] enum=[false]; code:string [规范声明必填] enum=["AUTH_SESSION_LIMIT", "AUTH_SESSION_ISSUANCE_LIMIT"]; message:string [规范声明必填]；429 application/json 字段：success:boolean [规范声明必填] enum=[false]; code:string [规范声明必填] enum=["AUTH_SESSION_LIMIT", "AUTH_SESSION_ISSUANCE_LIMIT"]; message:string [规范声明必填]。

迁入差异：AUTH-DOC-CONFLICT：登录 OpenAPI 的 security 与路由用途不一致，以真实处理器链为准。

来源：router/api-router.go:85；controller.PasskeyLoginFinish controller/passkey.go:337；上游 api.json 中 POST /api/user/passkey/login/finish。

CORE-AUTH-037 · POST /api/user/passkey/register/begin

用途与归属：开始注册Passkey。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）；处理器安全证明用途：VerificationScopePasskeyRegister。

返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 data, expires_at, flow_token, message, options, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:107；controller.PasskeyRegisterBegin controller/passkey.go:45；上游 api.json 中 POST /api/user/passkey/register/begin。

CORE-AUTH-038 · POST /api/user/passkey/register/finish

用途与归属：完成注册Passkey。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）；处理器安全证明用途：VerificationScopePasskeyRegister。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:108；controller.PasskeyRegisterFinish controller/passkey.go:121；上游 api.json 中 POST /api/user/passkey/register/finish。

CORE-AUTH-039 · POST /api/user/passkey/verify/begin

用途与归属：开始验证Passkey。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）。

请求：Body 类型：controller.passkeyVerifyBeginRequest controller/passkey.go:28；允许写入字段按处理器白名单，不把整个数据库结构直接开放。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:109；controller.PasskeyVerifyBegin controller/passkey.go:492；上游 api.json 中 POST /api/user/passkey/verify/begin。

CORE-AUTH-040 · POST /api/user/passkey/verify/finish

用途与归属：完成验证Passkey。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）。

返回：200 成功（上游未声明响应 Schema）；处理器使用 common.ApiSuccess 包络；代码 JSON/映射中观察到 message, method, scope, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:110；controller.PasskeyVerifyFinish controller/passkey.go:574；上游 api.json 中 POST /api/user/passkey/verify/finish。

CORE-AUTH-041 · POST /api/user/register

用途与归属：用户注册。优先沿用，迁入/适配后验收。

鉴权：未挂 User/Admin/Token 认证；按处理器及配置校验。

请求：Body 字段（application/json）：username:string [规范未列必填]; password:string [规范未列必填]; email:string [规范未列必填]; verification_code:string [规范未列必填]; aff_code:string [规范未列必填]。

返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 Error, message, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:77；controller.Register controller/user.go:215；上游 api.json 中 POST /api/user/register。

CORE-AUTH-042 · POST /api/user/reset

用途与归属：重置密码。优先沿用，迁入/适配后验收。

鉴权：未挂 User/Admin/Token 认证；按处理器及配置校验。

请求：Body 字段（application/json）：email:string [规范未列必填]; token:string [规范未列必填]; password:string [规范未列必填]。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:46；controller.ResetPassword controller/misc.go:281；上游 api.json 中 POST /api/user/reset。

CORE-AUTH-043 · GET /api/user/sessions

用途与归属：查看登录会话。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）；处理器额外要求浏览器登录 Session，账户访问令牌/PAT 不等价。

请求：浏览器 Session 身份必需；账户访问令牌/PAT 不替代该上下文。

返回：success/message/data；data 为当前用户的登录 Session 列表，来自 ListLoginSessions。

验收需求：当前设备标识、他人会话不可见、PAT 不能绕过 requireBrowserSession。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:94；controller.GetLoginSessions controller/auth_session.go:97；上游 api.json 中 GET /api/user/sessions。

CORE-AUTH-044 · DELETE /api/user/sessions/:sid

用途与归属：撤销指定登录会话。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）；处理器额外要求浏览器登录 Session，账户访问令牌/PAT 不等价。

请求：Path：sid（必填；以实际路由名为准）。OpenAPI 参数：path.sid:string（必填）。处理器读取：path.sid。自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。

返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 code, current, data, message, revoked_sid, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:95；controller.DeleteLoginSession controller/auth_session.go:110；上游 api.json 中 DELETE /api/user/sessions/{sid}。

CORE-AUTH-045 · POST /api/user/sessions/revoke-others

用途与归属：撤销其他登录会话。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）；处理器额外要求浏览器登录 Session，账户访问令牌/PAT 不等价。

请求：当前浏览器 Session，无必填 JSON；当前用户与 sid 从可信 Session 取得。

返回：success/message/data.revoked_count；保留当前 Session，撤销该用户其他 Session。

验收需求：一设备/多设备、重复请求结果、其他用户不受影响、被撤销设备后续失效。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:96；controller.RevokeOtherLoginSessions controller/auth_session.go:138；上游 api.json 中 POST /api/user/sessions/revoke-others。

CORE-AUTH-046 · GET /api/verification

用途与归属：发送邮箱验证码。优先沿用，迁入/适配后验收。

鉴权：未挂 User/Admin/Token 认证；按处理器及配置校验。

请求：OpenAPI 参数：query.email:string（必填）。处理器读取：query.email。自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。

返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 message, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:44；controller.SendEmailVerification controller/misc.go:219；上游 api.json 中 GET /api/verification。

CORE-AUTH-047 · POST /api/verify

用途与归属：通用安全验证。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）。

请求：Body 类型：service.VerificationInput service/security_verification.go:404；允许写入字段按处理器白名单，不把整个数据库结构直接开放。

迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。

来源：router/api-router.go:71；controller.UniversalVerify controller/secure_verification.go:137；上游 api.json 中 POST /api/verify。

CORE-AUTH-048 · GET /api/verify/methods

用途与归属：GetVerificationMethods。优先沿用，迁入/适配后验收。

鉴权：客户登录身份（沿用上游 UserAuth 支持范围）。

请求：处理器读取：query.scope。自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。

返回：上游 OpenAPI 无本项响应规范；按处理器返回值补齐成功、拒绝和错误结构；处理器使用 common.ApiSuccess 包络；代码 JSON/映射中观察到 message, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。

迁入差异：OPENAPI-MISSING：源码已注册，上游 OpenAPI 无匹配操作。

来源：router/api-router.go:70；controller.GetVerificationMethods controller/secure_verification.go:22。

当前本地实现切片

Core 已在显式身份模式中接通 6 条密码/会话路由与 3 条受保护 Key 读取路由。上方完整清单仍是上游参考范围，不代表全部支持；精确实现和差异见会话执行记录。

Core：登录、会话与账户安全

On this page