46 lines
5.3 KiB
Markdown
46 lines
5.3 KiB
Markdown
# Foundry 身份接入
|
||
|
||
复用 `/Users/zzyang/endoleap` 中已实现的 PKCE 和服务端会话模式。后端来源核对：Foundry Core 当前平台/认证源码、`internal/auth/auth.go`、`email.go`、`slack.go` 与 README 的 Browser session lifetime。
|
||
|
||
## 注册前端项目
|
||
|
||
英文品牌为 Thesisly；当前本地目录为 `/Users/zzyang/thesisly`，建议后端项目 ID 使用 `thesisly`。后端 Gitea Variables 中的 `FOUNDRY_PROJECTS` 应保留现有 JSON 条目，追加新项目：
|
||
|
||
```json
|
||
{"thesisly":"http://localhost:17322/auth/callback"}
|
||
```
|
||
|
||
这只是新增项示例，**不要用此单项覆盖全部现有项目**。前端 `.env.local` 的 `FOUNDRY_PROJECT` 必须与键完全相同，`APP_ORIGIN=http://localhost:17322`。第三方平台 Google/Slack 回调依然指向共享 Foundry 后端，不改为前端地址。本前端不配置CI/CD。此次已对正式 Core 执行仅配置重载，保留原有 endoleap、notes、board，并追加 thesisly；复用原镜像和发布二进制，没有发布工作分支代码。
|
||
|
||
## 流程
|
||
|
||
1. OAuth生成随机verifier和SHA256 challenge，verifier仅存当前标签的sessionStorage；顶部导航至同源 `/api/oauth/google|slack` 再跳转Core。
|
||
2. `/auth/callback`读取 fragment 中的一次性code/error或verify_email，立即清理地址栏，再向同源代理兑换。StrictMode重复effect复用同一兑换promise，避免重复消费一次性码。
|
||
3. 代理把access_token存入本站独立名的HttpOnly、SameSite=Lax Cookie，不返回客户端；不用localStorage保存token。
|
||
4. 通过auth/me恢复刷新后的登录状态；authenticated响应的`X-Foundry-Session-Expires-In`驱动Cookie续期，最多30天，绝对90天限制由Core执行。401清Cookie，暂时502保留现有Cookie并显示重试，不假装登录已失效。
|
||
5. 退出先撤销Core会话；成功后清Cookie，失败保留会话并告知重试。
|
||
6. 代理按路径/方法白名单，限制16KiB请求体；mutation必须与配置的APP_ORIGIN严格同源，跨站请求拒绝。生产HTTPS通过APP_ORIGIN启用Secure。
|
||
|
||
## 真实验收状态
|
||
|
||
Google和Slack均已完成真实授权登录：服务端分别观察到Thesisly的两种提供方身份记录，用户随后分别明确确认刷新保持、新标签保持、退出后刷新三项均正常。Google首次授权还完成了项目账户注册。浏览器控制工具连接超时，因此浏览器操作结果以用户实测反馈为据，不冒称自动浏览器验收，也未读取个人浏览器Cookie或token。
|
||
|
||
授权入口与取消回调也已分别验证。邮箱表单及验证回调的接线有自动化覆盖，但邮件实际投递和收件验证未实测；不将该可选链路表述为已完成真实投递验收。
|
||
|
||
## 代理验收
|
||
|
||
App Router 的 route.ts 直接调用 src/lib/auth-gateway.mjs。tests/auth-gateway.test.mjs 在不编译/启动Next.js的情况下，用标准Request/Response执行同一代理：验证兑换只转发允许的请求头、token只存HttpOnly Cookie、登录成功必须有有效期限、邮件注册不要求立即签发会话、短期续期、撤销后清Cookie、异常时保留Cookie、401清理、请求体限制、同源校验和429重试时间。异常响应中的access_token/refresh_token同样从浏览器响应剥离。退出时若Core已判定会话失效，客户端直接清理已结束的登录状态。
|
||
|
||
## 2026-11-07 配置更新
|
||
|
||
用户已确认新增 Thesisly 的 FOUNDRY_PROJECTS 回调。FOUNDRY_RESEARCH_DATABASE 为已撤回的 SQLite 路径方案，无需添加。论文库已完成 PostgreSQL 迁移及验收，Core 的论文 API 已通过临时回环服务接入前端。正式 Core 项目注册现已生效，新旧四个项目匿名 auth/me 均返回401；Google/Slack 实际授权地址和取消回调已验证。Google/Slack真实授权及用户侧会话保持、退出检查均已通过；邮件实际投递与验证未实测。
|
||
|
||
配置重载第一次因公网 TLS 探测超时而回退，已确认旧服务健康；随后按现有部署脚本使用回环 TLS、真实 SNI 与证书验证完成切换。服务器受保护验收记录为 foundry/verification/thesisly-config-foundry-core-1595929e8395.json，包含未变更的发布二进制 SHA256 和旧路由备份位置，不含认证凭据。
|
||
|
||
## 浏览器会话回归
|
||
|
||
`pnpm test:session` 使用系统 Chrome 和独立端口17323/17324：复制应用源文件到可清理的临时目录，运行真实 Next dev、App Router 代理与浏览器，只有 Core 响应为合成服务。它不会读取项目 .env、占用17322预览、发送真实密码或连接真实 OAuth。其中7项测试验证HttpOnly/SameSite Cookie及客户端无token、刷新/新标签恢复、跨标签退出、暂时故障后重试、失效清理、退出失败保留会话，以及Google/Slack模拟PKCE和邮箱验证的一次性消费。它证明前端会话接线，不证明真实Core数据、邮件投递、提供方授权或生产配置。
|
||
|
||
|
||
另外2项浏览器用例使用同一隔离dev和合成论文API，验证400/429/503/504时保留搜索条件、隐藏未知总数和分页、缩小查询后恢复，以及格式异常响应不会显示成空结果或退回样本。共9项浏览器回归已通过。真实库上也验证了宽泛搜索超时后修改为CartoonGAN可恢复3条结果；宽泛全文精确计数可能超出8秒预算，这是当前已知限制，用户可保留条件直接缩小查询或重试。
|