# 浏览器退出与回调协议

退出产品会话与结束UC会话分为本地撤销、取得上游导航地址、浏览器跳转和回调。各阶段的成功范围不同，不能只以HTTP200或页面跳转判定全部退出完成。

## 发起产品退出

`POST /auth/logout`。需要有效产品会话及与存储hash匹配的CSRF Cookie。当前裸退出handler从Cookie取得CSRF；普通受requireIdentity保护的产品写API另从单个X-CSRF-Token读取值，不能跨路径套用同一描述。前端正常sso写调用会同时携带该header；

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

JSON示例只展示目标与账号UI语言；Cookie由浏览器会话流程取得：

```json
{"return_to":"/workspace/example?tab=run#log","locale":"en-US"}
```

:::::
:::::{tab-item} 参数说明

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| return_to | body | 可选安全相对路径；省略采用/，显式空字符串被拒绝；安全规则同登录目标 |
| locale | body | 可选账号UI语言；trim后必须属于六个支持值；显式空字符串被拒绝 |

最多4096字节，拒绝未知字段及第二个JSON对象。空体或JSON null按零值请求处理；不能把同文件奖励接口的1MiB上限用于此处。请求没有业务工作区参数。

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{"code":"OK","data":{"logout_url":"https://uc.example.test/example-end-session"}}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| code | string | OK；当前成功封套没有msg |
| data.logout_url | string | 浏览器下一步应导航的UC退出地址；可能包含id_token_hint等敏感值，不记录完整地址到公开日志 |

返回200前，本地会话撤销已提交；但尚未证明UC退出完成。浏览器须按返回地址继续导航并完成回调。若地址构造/发现失败，本地撤销也可能已发生，不能从错误响应断定完全未执行。失败后应按实际会话和错误判断恢复，避免自动重放旧state。

:::::
::::::
:::::::

错误可为400 ErrParamInvalid、401 unauthenticated、403 ErrForbidden、502 ErrServiceUnavailable或500 ErrServer；msg为HTTP状态文本。前端请求失败时保留本地状态并停导航，不代表后端本地会话一定仍有效。

## 完成退出回调

`GET /auth/logout/callback?state=<服务端签发状态>`。state来自上游退出交接，不能由调用者自己创建。

service在同一事务消费未过期、未消费的退出state并创建新的登录状态；handler清会话/CSRF Cookie、设置新登录绑定，然后302到新登录导航。它不是静态“已退出”页面，也不意味着自动完成了新登录。

## GET退出入口

`GET /auth/logout`当前路由直接返回405，不返回退出URL或清会话。它是显式拒绝分支，不新增普通GET退出能力页，不以其他部署旧链接推断本源码支持。
