admin
90a3790a98
身份仍源自 OAuth provider（user_id = OIDC sub），cdrop 在其上自维护一薄层： 自签会话令牌 + accounts 表，并新增扫码快速登录。实施蓝本见 AUTH.md。 后端 · 自签会话原语 - web_sessions 加 kind/scope/granted_by 列（bootstrap 幂等迁移）；既有 oidc 会话行为不变，新增 self（滑动续期）/ guest（受限·不续）两类 - cdrop 自签 HS256 会话 access token，密钥派生自 SESSION_SECRET，与落盘 AES、 shortcut HS256 三密钥域隔离；jwtauth.verifySelfToken 无状态校验、靠 typ 区分 - requireFullSession 守卫：guest 会话不得改账号 / 再批准设备 / 签长效 token - /auth/refresh 按 kind 分流：self/guest 纯自签、不触 IdP 后端 · 扫码登录（internal/httpapi/qr.go） - qr/start・status・request・approve・deny 五端点 + login_requests 表 + reaper - 三密钥分离：QR 仅含批准信息，会话只投递给持私有 poll_secret 的原设备 （偷拍 QR 者无 poll_secret 领不到会话、未登录批不了准） - 会话在新设备侧领取（cookie 不经手机）、单次消费、短 TTL 后端 · 薄账户层与 2FA step-up - accounts 表（键 sub，不含任何凭证）：exchange/refresh upsert match_key / 显示名 / 头像 / roles，供显示与未来管理员开启迁移标记时跨源关联 - step-up（默认关）：开启后 qr/approve 要求新鲜 prompt=login 授权码，后端就地 换 id_token、JWKS 验签 + auth_time 窗口 + sub 匹配，provider 2FA 于此往返强制 前端（web/） - 显码页 /link/new + 批准页 /link + net/qr.ts，对齐 Theme B、复用 AuthShell 与聚珍排版管线、零新全局样式 - step-up 再认证流：批准前跑 prompt=login PKCE，回调分叉（不消费一次性 code、 独立 state key）后带 step_up_code/verifier 调 approve - 三语 i18n qr.*；新增 qrcode 依赖 修复 · clipboard sweeper（早已提交的损坏） - ClearExpiredClipboards 因 clipboard.sql 全角注释触发 sqlc 1.31 多字节偏移 bug，生成 SQL 被截断为「UPDATE clipboard_state SET content =」，sweeper 运行 期报「incomplete input」、过期剪贴板内容从未清除（短 TTL 暴露保护失效） - 注释改纯 ASCII 并加 bug 警告，重生成得完整 SQL；prod 已验证 sweeper 由 ERROR 转为正常清理（cleared count=1） 构建 - .dockerignore：排除本地 node_modules 等，避免宿主原生二进制污染镜像内 vite 构建 - Dockerfile.base：GOPROXY 改为可经 --build-arg 覆盖（默认仍官方代理，受限网络 构建时传区域镜像即可，仓库不固化区域值） 文档 - 新增 AUTH.md（账户与登录实施蓝本）；README 特性；.env.example / compose.snippet 增配置项（QR / 自签会话 TTL / step-up / match_claim） 测试 - 自签 token 密钥域隔离、扫码端到端（领取 / 单次 / poll_secret 校验 / deny / step-up 门）、extractIdentity、web_sessions 升级迁移
167 lines
8.7 KiB
Markdown
167 lines
8.7 KiB
Markdown
# cdrop — Commilitia Drop
|
||
|
||
跨 OS 剪贴板与文件传输服务。架构文档（`PROJECT_BRIEF.md` / `FRONTEND_DESIGN.md`）与 Changelog 位于 **`docs` 分支**：
|
||
|
||
```sh
|
||
git worktree add ../cdrop-docs docs # 并列检出，main / docs 互不扰动
|
||
open ../cdrop-docs/PROJECT_BRIEF.md
|
||
open ../cdrop-docs/CHANGELOG.html
|
||
```
|
||
|
||
## 克隆
|
||
|
||
前端 `web/src/lib/cjk-autospace/` 为 submodule（聚珍 / Juzhen 2.0：CJK 综合排版——中西间隙 / 长英文断词 / 标点挤压 / 禁则 / justify，跨 Claude / Nvim / cdrop 共享）。首次 clone 须带 `--recurse-submodules`，否则 `vite build` 会因找不到 import 而失败：
|
||
|
||
```sh
|
||
git clone --recurse-submodules <URL> cdrop
|
||
# 已 clone 但未拉 submodule：
|
||
git submodule update --init --recursive
|
||
```
|
||
|
||
## 当前阶段
|
||
|
||
MVP（M0–M13）已上线 prod（OIDC PKCE 接入自建 Casdoor，Cloudflare Realtime TURN over TLS）。其后进入阶段二，已落地：
|
||
|
||
- **剪贴板同步**：单条覆写式云剪贴板（短 TTL 限暴露面）+ 文本消息一次性通道
|
||
- **桌面客户端**：Wails v2（macOS universal `.app` + Windows `.exe`）—— 瘦客户端复用 web，业务全走后端 API；refresh_token 存系统密钥库（信封加密）
|
||
- **浏览器免重登 + PWA**：可安装为独立 PWA；浏览器侧 refresh_token 不再进 JS，改由服务端 HttpOnly cookie 会话持有（AES-256-GCM 落盘），关闭重开自动免重登（7 天滑动失活），设备名随会话持久化（抗 PWA 存储清除）
|
||
- **推送通知**：页面 / PWA 关闭时，收到文件、消息、传输完成或失败以系统通知提醒；页面打开时仍走应用内提示。网页走 Web Push（VAPID，覆盖浏览器 / Android / iOS 16.4+ 已安装 PWA），桌面客户端走原生系统通知（仅窗口非前台才弹）。文案按设备语言在服务端渲染（中简 / 中繁 / 英）
|
||
- **扫码登录**：临时借用陌生设备时，陌生设备显二维码、已登录手机扫码批准即可登入（微信 / WhatsApp 网页版模型）。批准方选“信任此设备（7 天）”或“仅此次（1 小时）”，授予的是受限访客会话（能收发文件，不能改账号 / 不能再批准别的设备 / 不能签发长效 token）。三密钥分离：二维码只含批准信息，会话只投递给持私有轮询密钥的原设备，偷拍二维码者拿不到会话。身份仍源自 OAuth provider，cdrop 自维护薄账户层 + 自签会话令牌（详见 `AUTH.md`）
|
||
- **iOS Shortcut**：HS256 scoped token 手动签发路径（网页签发 UI 暂停）
|
||
- **安全加固**：中继会话防耗尽、HS256 强制 jti、prod 强制 audience、TURN 短 TTL、OAuth 端点限流（详见 CHANGELOG）
|
||
|
||
MVP 里程碑（历史记录）：
|
||
|
||
| 里程碑 | 内容 | 状态 |
|
||
|---|---|---|
|
||
| M0–M5 | 后端：chi / sqlite WAL / dev+prod auth 中间件 / SSE Hub / signaling + 状态机 / Relay ring buffer | 完成 |
|
||
| M6–M10 | 前端：Mantine + TanStack Router + Zustand（其后叠加自定义设计 token 与 Theme B 重塑）/ 自实现 SSE / WebRTC P2P / Relay 回退 / SSE 重连 + chunk 重试 | 完成 |
|
||
| M11 | 本机双 tab 端到端验收（dev mock auth）+ 多轮 bug 修复（race / 状态机 / DOM nesting / 状态着色） | 完成 |
|
||
| M12 | OIDC PKCE：后端 /api/auth/{config,exchange,refresh} 代理 token endpoint，前端 PKCE redirect + callback；Casdoor confidential client + client_secret | 完成 |
|
||
| M13 | 部署：cdrop-base 缓存层 + 应用镜像（BUILDPLATFORM 跨编译，6 MB distroless），Cloudflare Realtime TURN App，反代 reverse_proxy + flush_interval -1（SSE 友好），h3 已启 | 完成 |
|
||
|
||
## 本机开发：两 tab 验收流程（M11）
|
||
|
||
### 1. 准备 dev token
|
||
|
||
把同一个随机 base64 串同时写到两份 env 文件：
|
||
|
||
```bash
|
||
TOKEN=$(openssl rand -hex 32)
|
||
|
||
cp .env.example .env
|
||
sed -i '' "s|replace-with-32-byte-random-base64|$TOKEN|" .env
|
||
|
||
cp web/.env.example web/.env.local
|
||
sed -i '' "s|replace-with-32-byte-random-base64|$TOKEN|" web/.env.local
|
||
```
|
||
|
||
`.env` 会被根目录的 Justfile 自动加载（`set dotenv-load := true`）。
|
||
|
||
### 2. 起后端（dev 模式）
|
||
|
||
```bash
|
||
just dev-back
|
||
# 监听 :8080，json 日志到 stdout
|
||
```
|
||
|
||
后端要求 `CDROP_AUTH_MODE=dev` 与 `CDROP_DEV_TOKEN` 同时设置；缺一会 panic 拒启动（防止误带到生产）。`.env` 文件由后端自动加载（koanf）。
|
||
|
||
### 3. 起前端（vite dev）
|
||
|
||
另开一个终端：
|
||
|
||
```bash
|
||
just dev-front
|
||
# 默认 http://localhost:5173，/api 自动代理到 :8080
|
||
```
|
||
|
||
### 4. 打开两个浏览器 tab
|
||
|
||
| tab | URL | 期望 |
|
||
|---|---|---|
|
||
| tab-1 | `http://localhost:5173/login?dev_user=alice` | 输入 `Continue` → Setup 输入设备名 `tab-1` → Home |
|
||
| tab-2 | `http://localhost:5173/login?dev_user=alice` | 同上但设备名填 `tab-2` |
|
||
|
||
两 tab 的 Home 页应在 1–2 秒内互相看到对方在线，顶部 `● online` 亮绿。
|
||
|
||
### 5. 验收 brief §7 五条
|
||
|
||
| # | 步骤 | 通过标准 |
|
||
|---|---|---|
|
||
| 1 | 双 tab Casdoor 登录 | M11 阶段使用 dev mock 等价：两 tab 都进 Home |
|
||
| 2 | Home 页看到对方在线 | DeviceStrip 互相显示对方卡片，绿点 |
|
||
| 3 | 拖拽文件 → P2P 直传 | tab-1 选 tab-2 + 拖文件 → Send；tab-2 浏览器自动下载，sha256 与原文件一致 |
|
||
| 4 | 模拟 NAT 阻塞 → fallback Relay | DevTools console 注入 `RTCPeerConnection.prototype._origCreateOffer = RTCPeerConnection.prototype.createOffer; RTCPeerConnection.prototype.createOffer = function() { return new Promise(()=>{}) }`（永远 pending），30s 后看 transfer 状态切到 `RELAY_ACTIVE`，依然下载成功 |
|
||
| 5 | 传输中关闭一方 → 重连续传 | M11 范围内可手动 kill backend 几秒再起；或断网卡 30s |
|
||
|
||
`> 100 MB` 文件不会自动接受（brief §2 阈值）；当前 MVP 还没接 UI 二次确认，可暂停在大文件场景验证。
|
||
|
||
### 6. 单元测试
|
||
|
||
```bash
|
||
just test # go 测试
|
||
just typecheck # 后端 go vet 由 just vet 触发
|
||
cd web && npm run typecheck && npm run build
|
||
```
|
||
|
||
## 部署
|
||
|
||
后端编译进单个 distroless 镜像（前端经 Dockerfile 构建后 `go:embed` 进二进制）。镜像约 6 MB。
|
||
|
||
### 构建镜像
|
||
|
||
```bash
|
||
# 依赖预热（仅 go.mod/go.sum 或 web/package*.json 变动时需重跑）：把 Go modules
|
||
# 与 node_modules 烤进 cdrop-base:latest，加速后续源码层构建。
|
||
just docker-base
|
||
|
||
# 应用镜像：从 cdrop-base 起步编前端 + 跨编译 Go，落 linux/amd64 distroless。
|
||
just docker-image # → cdrop:latest
|
||
```
|
||
|
||
宿主原生 arch 即可（`BUILDPLATFORM` 让 Go 跨编译走原生，无需 qemu 执行 amd64）。
|
||
|
||
### 上线
|
||
|
||
镜像送到目标主机（二选一）：
|
||
|
||
```bash
|
||
# A. 本地构建 → 传镜像（无需在服务器装 Node/Go）
|
||
docker save cdrop:latest | gzip | ssh <user>@<host> 'docker load'
|
||
|
||
# B. 或把源码同步到服务器，在服务器上 docker build
|
||
```
|
||
|
||
服务条目模板见 [`docker/compose.snippet.yaml`](docker/compose.snippet.yaml)：填进你的 `docker-compose.yaml`，挂一个目录到 `/data`（存 SQLite 库），不开放端口、由反代访问 `<service>:8080`。
|
||
|
||
```bash
|
||
docker compose up -d <service>
|
||
curl -s https://<your-domain>/healthz # {"status":"ok","auth_mode":"prod","db_ok":true}
|
||
```
|
||
|
||
### 反代（SSE 要点）
|
||
|
||
cdrop 用 SSE 推事件，反代**必须关闭响应缓冲**否则事件不实时。Caddy 示例：
|
||
|
||
```caddyfile
|
||
your-domain.example {
|
||
reverse_proxy <service>:8080 {
|
||
flush_interval -1 # 关闭缓冲，SSE 即时下发
|
||
}
|
||
}
|
||
```
|
||
|
||
### prod 配置
|
||
|
||
env 见 [`.env.example`](.env.example) / `compose.snippet.yaml`。要点：
|
||
|
||
1. `CDROP_AUTH_MODE=prod`，删掉 `CDROP_DEV_TOKEN`
|
||
2. 填 `CDROP_OIDC_*`（你的 OIDC provider，如自建 Casdoor / Keycloak）；在 IdP 建 confidential + PKCE client，回调白名单加 `https://<your-domain>/oauth/callback`
|
||
3. **`CDROP_OIDC_AUDIENCE` 必须非空**（你的 client_id，多值逗号分隔）—— 留空会跳过 audience 校验，同一 JWKS 下其他应用的 token 也能验过；后端 prod 启动期强制此项，缺则拒启动
|
||
4. **`CDROP_SESSION_SECRET` 必须非空**（任意长度高熵串）—— 浏览器免重登会话的 refresh_token 落盘加密密钥（内部 SHA-256 派生 AES-256 密钥）；后端 prod 启动期强制此项，缺则拒启动
|
||
5. 设 `CDROP_HS256_SECRET`（iOS Shortcut scoped token 用，不用可留空）
|
||
6. 可选 `CDROP_CF_TURN_KEY_ID` + `CDROP_CF_TURN_API_TOKEN` 启用 Cloudflare Realtime TURN over TLS（不配则前端 STUN-only 兜底）
|
||
7. 可选 `CDROP_VAPID_PUBLIC_KEY` + `CDROP_VAPID_PRIVATE_KEY` 启用 Web Push 推送通知（用 `just vapid-keygen` 生成一对；两者须同时设置，半对则拒启动；都留空则推送惰性关闭，不阻塞启动）。`CDROP_VAPID_SUBJECT` 可选（联系标识，留空回退站点 URL）
|
||
|