Bind Feishu identity to OpenVPN sessions and refine management UI

docs/specs/SDD-007-built-in-feishu-issuer.md

@@ -93,3 +93,31 @@
 真实飞书授权及 OpenVPN 建链现已在实例日志中验证。配置页输入 App ID/Secret 后延迟调用已有 HTTPS 管理员查询接口：成功读取企业信息才显示 `tenant:tenant:readonly` 已验证，并自动填入 tenant_key；失败仅展示脱敏错误并允许重试。`contact:user.base:readonly` 是用户授权范围，不能仅靠应用凭据证明；首次成功换取用户资料并校验租户后记录无用户标识的验证时间，换应用凭据或租户时清除，设置页只展示是否曾通过。服务端启动或页面刷新不重复发起 OAuth，也不把手填 tenant_key 当作验证通过。密钥只经 HTTPS 管理接口传输，页面异步请求需忽略被新输入覆盖的旧响应。
 
 认证组件通过原生 `http.template` 加载每实例的 0600 HTML 页面；页面只提示返回客户端查看连接状态，不在可能复用的终态模板上错误宣称 VPN 已连接。不额外放宽 Nginx 路径。验收：凭据变更后状态清零，查询正确/错误与旧响应均不误报；首次真实登录后状态可见；插件能正常加载模板并保持浏览器认证、OpenVPN 建链。发布时先构建测试，再替换二进制并重启受影响的 OIDC 实例以应用新模板；若插件不兼容模板，回退之前的配置与二进制、重启实例，旧认证仍可使用。数据库新列由 AutoMigrate 添加，回退版本忽略该列。
+
+## 12. 在线会话的未知身份（S1）
+
+OpenVPN `status-version 3` 的第 1 列 Common Name 与第 9 列 Username，在无客户端证书的 WebAuth 首次连接时都可能为 `UNDEF`。目前会话同步把占位字符串当作拨号用户名，误写入在线会话及审计。优先使用有效 Username，其次使用有效证书 CN；两列均为 `UNDEF` 时留空，并在在线会话及连接审计页面明确显示“身份未识别”。保持原流量快照键以避免部署后的首次轮询重复计数；不根据公网 IP、姓名或认证时间猜测身份，更不把“LG”这样的显示名自动绑定 VPNUser。已有历史日志保留原值，仅页面标记其身份未识别。
+
+验收：密码与证书连接仍展示其用户名/CN；无身份的 WebAuth 状态行不会记录 `UNDEF` 为 VPNUser，也不会误关联飞书人员；在线会话保留连接地址与流量。若同一连接随后获得可信 Username，沿用此前 `UNDEF` 流量快照计算增量，不把旧流量重复累计；单元测试覆盖未知身份、重复轮询和后续获得稳定 subject 的过程。真正按人展示还需验证 `openvpn-auth-oauth2` 是否能向 OpenVPN 提供带稳定 subject 的 Username；如插件不传递，须在认证阶段增加可信映射，不能用会话 IP 推断。此修复不改变认证权限或 Nginx；发布前运行 OpenVPN 单元测试及前端构建，发布后检查真实状态文件第 1/9 列与在线会话，失败则恢复旧管理二进制，保留数据库和专线进程。
+
+## 13. 授权身份传递与回调结果页（S2）
+
+现有 `fetchFeishuUser` 从飞书 `/authen/v1/user_info` 读取 `open_id`、`tenant_key`、`name`，`/id/userinfo` 输出稳定 `sub` 与 `name`；但 ID Token 仅包含 `sub`。浏览器 `/oauth2/callback` 是认证组件消费授权码的端点，地址栏的 code 不能代表用户资料。将已获取的非空姓名作为标准 OIDC `name` claim 加入 ID Token；`sub` 继续由 `tenant_key:open_id` 组成，不能以可变姓名替代。结果模板改为简洁蓝白灰页面，继续保持结果中性，不能输出令牌、姓名或根据地址栏宣称 VPN 已连通。
+
+FR-13-01：模拟飞书换码与用户信息返回时，服务端传递稳定标识与姓名，签发的 ID Token 在非空时包含 `name`，`/id/userinfo` 保留原字段；空姓名不写入空 claim。FR-13-02：同一 0600 模板通过 `http.template` 用于回调终态，无论认证结果如何都只提示切回客户端检查状态。
+
+AC-13-01：模拟上游含 `open_id`、`tenant_key`、`name` 的响应，验签并检查 ID Token 的 `sub`/`name`，验证名称为空时不增加 claim；运行身份模块测试。AC-13-02：读取生成的模板，核对页面标题、移动端视口及不出现回调参数/用户资料；运行 OpenVPN 模块测试。真实账号授权和 OpenVPN 状态第 1/9 列另需在线联调，单元模拟不等同于线上已显示真人姓名。
+
+风险：姓名属于个人信息，只放入面向已认证机密客户端的短时 ID Token 与现有 UserInfo，不写浏览器结果页或日志；上游未提供姓名时维持稳定 `sub`。兼容性：已有依赖 `sub` 的客户端行为不变；不增公网路由或数据库列。发布先构建并验证，再部署管理二进制、重启受影响的 OIDC 专线以生成新模板，检查 HTTPS 认证流程；失败回退二进制并重启该专线，不删除身份数据或签名密钥。
+
+## 14. WebAuth 身份进入 OpenVPN 会话（S3，待组件核实）
+
+现状证据：飞书回调读取 `tenant_key`、`open_id`、`name`，受限 OIDC Token 返回稳定 `sub`；实例配置 `openvpn.auth-token-user: true`，但服务端 `status-version 3` 的 Username 和 CN 仍可能都是 `UNDEF`。`auth-token-user` 是推送给客户端以后重新认证使用的用户名，不能证明服务端首次连接状态已绑定 OIDC subject。会话同步只信任 OpenVPN 状态文件，不应按公网 IP、浏览器回调时间或显示名匹配人。旧版代码把 `UNDEF` 直接写入审计，本地 S1 修正正在避免新增这类伪用户；历史审计保持原样。
+
+目标链路：飞书应用确认用户和租户 → OIDC 使用 `tenant_key:open_id` 作为稳定 subject、姓名只用于显示 → 认证组件验证令牌与 pending CID/KID 的绑定 → 在同一条管理接口 `client-auth` 的客户端配置中设置 `override-username <稳定 subject>` → OpenVPN 状态文件 Username 出现该 subject → 平台在线会话与审计使用这个 subject。OpenVPN 本地源码文档 `doc/man-sections/server-options.rst` 明确 `override-username` 会被状态输出采用；但须先核实当前 `openvpn-auth-oauth2` 版本是否支持下发此配置，若不支持，应修改/封装认证组件并在集成测试验证，不能在 `server.conf` 中静态设置一个共用用户名。将来展示飞书姓名需按 subject 保存受控身份资料或提供受限查询，不得将姓名当成授权键或自动关联同名 VPNUser。
+
+FR-14-01：每个成功认证的 OpenVPN CID/KID 必须绑定经验证的非空稳定 subject；缺失身份则拒绝授权，不得以 `UNDEF`、IP 或可变姓名补全。FR-14-02：状态文件的 Username 必须与该 subject 一致，平台在线列表和连接/断开审计使用该值；密码和证书专线保留原行为。FR-14-03：部署不得扩大 Nginx、管理 socket 或飞书资料接口的权限；失败时能回退认证组件与配置。
+
+AC-14-01：模拟两个并发 WebAuth 请求及其不同 CID/KID，证明不能交叉赋值，令牌验证失败、租户不符和空 subject 均拒绝；检查管理命令仅含安全编码的 subject。AC-14-02：测试专线真实授权后读取 `openvpn-status.log` 的 CN/Username、在线会话和连接/断开审计，三处能追溯同一稳定 subject；重复认证和重连无误绑定。AC-14-03：测试旧密码/证书连接、认证失败、组件崩溃恢复，并检查失败时无匿名会话被错误归到已认证用户。
+
+待决：当前运行的 `openvpn-auth-oauth2` 对 `client-auth` 配置和令牌 `sub` 的实际处理，以及线上状态文件原始列值；在没有组件源码/运行输出验证前，不声明此节已实现。发布顺序为先验证并编译组件、测试专线联调，再更新管理服务及组件，最后观察线上状态与审计；回退为恢复先前组件及配置并重启测试专线，保留密钥、身份数据和历史审计。