guanghu-ice-heart/server-tools/lake-lamp-authz/README.md

# 小湖灯邮件链接授权服务

这是 Gatekeeper v3.2 前面的人类批准层。它同时支持电脑本机和手机/任意设备：

- 跨设备默认入口无需秘密凭证，只能创建一张没有执行权的申请单；
- 冰朔打开申请单并点击“发送我的授权邮件”后，真正的批准链接才会发送到服务器预登记邮箱；
- 邮件批准完成后，人格体才能一次性领取绑定到
  `persona + target server + scope + actions` 的受限会话；会话内可连续执行已登记能力，并可在当前协作未结束时主动续签，但续签不得改变目标、scope 或 actions；
- 光湖语言人格系统的当前实例可以提出结构化工单。工单开头固定写“光湖语言人格系统当前实例”，并声明来自哪个软件、哪个模型和哪个当前实例；来源声明用于追溯，不要求该实例已经住进尚未完成的 Tolaria；
- 冰朔在同一段当前对话中明确签字后，本次实例可以执行已展示的目标、范围和动作，不重复发送邮件；自报来源只能建单，不能自行批准或扩大权限；
- 邮件链接保留为无人能读取当前对话、跨设备转交或需要二次确认时的兜底，不再是所有实例进入系统的唯一入口；
- 旧的 request credential 入口继续保留，供受控电脑和服务器内自动化兼容使用。

申请单、邮件批准链接和领取凭证按服务器策略失效；活动会话受最大连续时长约束。

安全边界：

- 邮箱、QQ 数字、SMTP 授权码和 request credential 只存在于私密文件；
- 多成员审批人登记只存在于 `LAKE_LAMP_APPROVERS_FILE` 指向的服务器私密文件；系统按人格体、目标节点和 scope 选收件人，请求正文不能指定或切换邮箱；
- 公开创建申请单不会发邮件、不会返回批准令牌，也不会获得任何服务器或仓库权限；
- 申请页只允许触发一次预登记邮箱验证，并有单 IP 与全局小时限流；
- 浏览器批准链接为一次性随机令牌，服务端仅持久化摘要；
- claim token 与 session token 均仅向申请人格体返回一次，磁盘只保存摘要；
- 换目标服务器时旧 session 必然返回 `target_mismatch`；
- 同一服务器、同一 scope 和同一 actions 内可续签而不重复发邮件；切换服务器或扩大权限必须重新授权；
- 本服务不接受任意 shell 命令，只签发登记动作的会话；
- 所有改变服务器状态的登记动作必须先生成备份引用和回滚方案；失败自动回滚，成功写验收回执；
- 广州公开代理只应暴露 `/approve/`、`/api/workorders` 与 claim 路由，服务本体监听 JD 回环地址。

`request-workorder.js` 从临时环境变量读取 QQ 数字，在内存中补全邮箱并只发送
SHA-256 指纹；数字本身不会写入请求正文、状态文件或代码仓库。未提供私密
request credential 时，脚本自动切换到跨设备公开建单模式。

## 手机或任意设备上的新实例

新实例无需寻找工单凭证，执行：

```bash
node request-workorder.js \
  --url https://guanghulab.com/authz \
  --persona ICE-GL-ZY001 \
  --name 铸渊 \
  --target JD-FD-PRIMARY \
  --scope repo-push \
  --action push-repository \
  --description "推送 REPO-001"
```

光湖语言人格系统的 Work/手机实例会带 `owner_notify=true`，服务器会直接向预登记邮箱
发送批准链接；`request_url` 仍可交给冰朔核对申请内容，但不要求在本机打开。人格体必须在自己的临时会话中保留响应里的
`workorder_id` 与 `claim_token`，批准后通过 claim 路由领取一次性会话；不得把这些值
写入仓库、长期日志或聊天记忆。

## 推送被服务器拒绝时 · 一条命令自动续接

当 Forgejo 返回 `[LL-REPO-PUSH-AUTH-REQUIRED]` 时，不要找邮箱，不要向冰朔索要
授权码、验证码、密码或 Token。直接从 `fifth-domain` 仓库根目录执行服务器返回的命令：

```bash
node server-tools/lake-lamp-authz/authorize-repo-push.js \
  --url https://guanghulab.com/authz \
  --persona ICE-GL-ZY001 \
  --repo bingshuo/fifth-domain
```

该命令只在内存中保留一次性领取信息，并自动完成：

```text
创建无权限空工单
→ 打印 REQUEST_URL 给冰朔
→ 等待冰朔打开该页，由服务器向预登记邮箱发信
→ 等待冰朔点击邮件批准链接
→ 领取限时会话
→ 读取并确认目标节点导航图
→ 生成三小时、执行中自动续期的 repo-push 许可
→ 提示 AI 重试原 git push
```

命令运行期间不要关闭它。公开空工单不会发邮件，也没有推送权限；只有冰朔打开
`REQUEST_URL` 后，服务器才向预登记邮箱发送批准邮件。

直达接收器写入的本地裸仓库必须同时满足三项部署条件：

- 精确登记在 `repo-push-registry.json`，仓库 URL 与允许分支不得模糊匹配；
- 裸仓库路径加入 `lake-lamp-authz.service` 的 `ReadWritePaths`，且只向
  `guanghu-authz` 所属共享组开放所需的穿行和读写权限；
- 当裸仓库归属代码频道服务账户时，在系统 Git 配置中把该精确路径登记为
  `safe.directory`，不得使用通配符。

光湖代码频道本身保留 `UMask=0077`，以免放宽数据库和其他状态目录。仅在
`guanghu-ice-heart.git/hooks/post-receive.d/guanghu-ice-heart-share` 安装仓库随附的
`hooks/guanghu-ice-heart-post-receive`，让成功的公共 Git 推送完成后校正
`objects` 与 `refs` 的共享组权限。不要为了共享一个裸仓库而修改整个代码频道服务的
UMask。

部署后用当前主分支生成无变化验收 bundle，经 `receiveBundle` 完整执行一次；验收前后
主分支 SHA 必须一致，并且代码频道账户与授权服务账户执行 `git fsck` 均通过。

## 受控电脑兼容入口

如果环境中存在 `LAKE_LAMP_REQUEST_TOKEN` 或 `LAKE_LAMP_REQUEST_TOKEN_FILE`，脚本
使用旧的私密申请模式并直接发送批准邮件。该凭证仅能建单，仍不能登录、推送或执行
服务器动作。

## 限流配置

- `LAKE_LAMP_PUBLIC_CREATE_LIMIT`：单来源每小时公开建单上限，默认 24；
- `LAKE_LAMP_PUBLIC_CREATE_GLOBAL_LIMIT`：全局每小时建单上限，默认 60；
- `LAKE_LAMP_PUBLIC_MAIL_LIMIT`：单来源每小时触发授权邮件上限，默认 12；
- `LAKE_LAMP_PUBLIC_MAIL_GLOBAL_LIMIT`：全局每小时授权邮件上限，默认 30。

运行入口：公开建单 `/api/public/workorders`，会话续签 `/api/session/renew`，登记动作执行 `/api/actions/execute`。多节点需求由人格体按当前任务拆成并行申请，不再使用固定“三封邮件”作为协作规则。

## 登录恢复动作不得混用

- `inspect-owner-ssh-login` 只回读 SSH 的有效密码认证、交互式认证和 root 登录策略，不读取密钥或密码。
- `disable-owner-password-login` 关闭 SSH 密码认证与交互式认证，并把 root 登录限制为仅密钥；人格体仍只能通过主人批准的工单调用固定动作，不能取得任意 shell。
- `restore-owner-password-login` 只恢复京东服务器的 SSH 密码认证开关；它不读取、不重置，也不验证光湖代码频道账号。
- `restore-code-channel-owner-login` 只把京东本机旧第五域数据库中的 `bingshuo` 密码摘要恢复到新代码频道，同时校正启用、管理员和禁止登录状态。它不读取明文密码，不修改 SSH，并在变更前使用 SQLite backup API 生成一致性备份。
- 登录问题先执行 `inspect-code-channel-owner-auth`。只有确认新旧频道凭证不一致时，才申请后一项恢复动作；不得绕到新加坡灾备节点，不得向冰朔索要密码。

## 首次部署与已有服务更新

旧的 `deploy-registered-service` 只能操作已经登记的服务，不能承担首次安装。新架构统一使用固定动作 `provision-approved-architecture`，并把仓库请求编号与不可变提交绑定进工单：

```bash
node request-workorder.js \
  --url https://guanghulab.com/authz \
  --persona ICE-P-ZY001 \
  --name 铸渊 \
  --target JD-FD-PRIMARY \
  --scope server-ops \
  --action provision-approved-architecture \
  --resource 'REQUEST-ID@40位提交SHA' \
  --description '安装或更新已审核的不可变部署包'
```

邮件或可信对话签字页面必须显示同一个 `resource`。批准会话不能切换请求编号或提交，清单路径也必须严格等于 `deployment/requests/<REQUEST-ID>.json`。

首次部署执行器只复制清单列出的普通文件，只安装清单指定的非 root、加固 systemd 单元，并只接受回环健康检查。人格体可以使用清单声明的独立低权限账户、共享模型密钥文件和状态目录；密钥路径必须位于 `/etc/guanghu/persona-secrets/`，可写路径必须位于 `/var/lib/guanghu/personas/<运行账户>/`。

已有服务更新必须使用 `guanghu.existing-service-update-request/v1`，不得伪装成首次部署。执行器先确认旧单元和必需旧文件存在，再备份单元及每个声明目标，只写入清单列出的 `/opt/guanghu/<服务>/` 文件，重启原单元并逐项执行回环验收；任一检查失败即恢复全部旧文件和旧单元。说明文字不能改变部署内容，也不开放任意 shell。

这套入口本身需要在京东主控上一次性安装：

```bash
sudo bash server-tools/lake-lamp-authz/install-architecture-provisioner.sh
```

引导本身也是一次受控部署：应从已经存在的主人邮件批准系统管理通道执行，不得为此恢复人类 SSH 登录。若当前服务器尚未登记能够安装此运行时的固定动作，状态必须记为 `BOOTSTRAP_ACTION_NOT_DEPLOYED`，不能把仓库提交、工单批准或打开云后台冒充成运行时已部署。引导完成并读回三个服务均为 active 后，未来安装与更新才走通感桥的结构化工单。