docs-site 会话 Cookie API

docs.wainao.chat（文档站）专用的会话 Cookie 同步端点。用户在文档站走完 OAuth PKCE 授权拿到 access_token 后，由此 API 把 token 写入 HttpOnly Cookie（wn_docs_session），供 nginx 的 auth_request 在访问 admin 文档前做权限校验。

这些路由通过 docs-site 容器内的 nginx 同源反代到后端 /docs-auth/*，对后端而言属于同源请求，因此无需任何 CORS 配置。

基础路径

/docs-auth

认证方式

两个端点本身都无需预先登录（公开端点）：

• /docs-auth/sync-cookie：身份凭据来自请求体里的 access_token，由后端校验该 token 是否有效且确实由文档站自身的 OAuth App 颁发。
• /docs-auth/logout：无需任何凭据，仅清除 Cookie。

Cookie 说明

属性	值
名称	wn_docs_session
属性	HttpOnly; Secure; SameSite=Lax; Path=/
取值	OAuth access_token（URL 编码后写入）
Max-Age	取 token 剩余有效期（秒），最小为 0

Cookie 为 host-only（仅 docs.wainao.chat 可见），客户端 JS 无法读取（HttpOnly）。

---

端点列表

POST /docs-auth/sync-cookie

把 OAuth access_token 校验后同步写入 wn_docs_session HttpOnly Cookie。

请求体

字段	类型	必填	说明
access_token	string	是	文档站 OAuth App 颁发的 access_token

后端校验流程：

1. 服务端必须配置 DOCS_AUTH_OAUTH_CLIENT_ID，否则返回 500。
2. 请求体必须为合法 JSON，否则返回 400。
3. access_token 必须为字符串且符合 OAuth token 格式，否则返回 400。
4. 按 token 哈希查 oauth_tokens，要求未撤销（revoked_at 为空）且未过期（expires_at 大于当前时间）。
5. 关联的 OAuth App 未被禁用（disabled_at）、未被删除（deleted_at）。
6. App 的 client_id 必须等于 DOCS_AUTH_OAUTH_CLIENT_ID（只接受文档站自身的 OAuth App）。

成功响应 200 OK

同时下发 Set-Cookie: wn_docs_session=<token>; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=<剩余秒数>。

{
  "ok": true,
  "expiresIn": 3600
}

字段	类型	说明
ok	boolean	固定 true
expiresIn	number	Cookie 剩余有效期（秒），即 token 距离过期的秒数（最小 0）

错误码

状态码	error	说明
400	invalid_body	请求体不是合法 JSON
400	access_token_required	缺少 access_token 或格式非法
401	invalid_token	token 查询失败 / 不存在 / 已撤销 / 已过期 / App 被禁用或删除 / client_id 不匹配 / 校验异常
500	service_misconfigured	服务端未配置 DOCS_AUTH_OAUTH_CLIENT_ID

---

POST /docs-auth/logout

清除 docs-site 会话 Cookie。无需任何凭据。

请求体

无。

成功响应 204 No Content

无响应体，同时下发清除 Cookie 的响应头：

Set-Cookie: wn_docs_session=; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT

错误码

无（始终返回 204）。