# Jupyter 代理与访问票据契约 V1

## 1. 浏览器访问流程

1. 前端携带用户、Workspace、`edit_session_id` 和 `lock_token` 调用
   `POST /api/v1/jupyter/access-tickets`。
2. Platform API 校验编辑锁、Runtime 与 Jupyter Session 的归属及状态。
3. 成功后返回 `/jupyter/...` 地址，并设置短期
   `jupyter_access` Cookie。
4. 前端在当前平台页面的编辑区内嵌同源 `/jupyter/...` 页面，不新开浏览器
   标签页。
5. 内嵌页面经 Nginx 访问 Jupyter HTTP/WebSocket；Nginx 先执行内部鉴权
   子请求，再把内部 Token 注入上游请求。

一个 Workspace 只建立或复用一个 Jupyter Runtime/Server；同一 Server
中的每个 Notebook 使用独立 Jupyter Session 和独立 Kernel。

浏览器响应、URL、JavaScript 和日志中都不得出现 Jupyter 内部 Token。

## 2. 访问票据

- 票据绑定：`user_id`、`workspace_id`、`edit_session_id`、
  `runtime_id`、`jupyter_session_id`。
- 默认有效期：60 秒；最长不超过 5 分钟。
- Cookie：`HttpOnly; SameSite=Lax; Path=/jupyter/`，生产环境必须增加
  `Secure`。
- 票据只授权当前 Workspace 的 Jupyter 路径，不能跨 Workspace 使用。
- Jupyter 页面必须与平台使用同一站点入口，并允许同源 iframe 嵌入。

## 3. Nginx 内部鉴权接口

```http
GET /internal/v1/jupyter/authorize
Cookie: jupyter_access=<opaque-ticket>
X-Original-URI: /jupyter/...
X-Request-ID: <request-id>
```

该接口只允许 Nginx 在内部网络调用：

- `204`：票据有效，响应头提供上游地址和内部认证信息。
- `401`：票据缺失、伪造或过期。
- `403`：用户、Workspace、Session 不匹配，或编辑锁/Runtime 已失效。

成功响应头：

```http
X-Jupyter-Upstream: http://jupyter:8888
X-Jupyter-Authorization: token <internal-token>
X-Workspace-ID: <workspace-id>
```

Nginx 必须删除客户端传入的 `Authorization`，使用内部鉴权结果重建上游
认证头。

## 4. WebSocket 约束

- `/jupyter/api/kernels/*/channels` 与其他 WebSocket 路径使用 HTTP/1.1。
- 转发 `Upgrade`、`Connection`、`Host`、`Origin` 和请求 ID。
- 关闭代理缓冲，读超时不小于 3600 秒。
- HTTP 和 WebSocket 使用同一票据校验规则。
- 连接关闭只断开交互连接，不自动停止 Workspace Runtime。
- Compose Demo 使用最长 5 分钟票据；前端必须继续发送编辑锁心跳，并在
  票据到期前重新签发。
- Jupyter Lab HTML 中出现的内部 Token 必须由 Nginx 在返回浏览器前清除。