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 回环地址。

## HoloLake 手机身份、知识湖与模型代理

HoloLake 手机端使用独立的邮箱验证码会话，不复用工单批准链接：

- `/api/hololake/session/email/request` 对已登记和未登记邮箱返回相同形态，避免枚举账号；
- 六位验证码只在邮件正文出现，服务器状态仅保存带私密 pepper 的摘要，十分钟失效且最多尝试五次；
- 会话绑定 HoloLake 设备编号，手机仅保存短期会话令牌；服务器磁盘仍只保存令牌摘要；
- `/api/hololake/knowledge/manifest` 与 `/archive` 只暴露固定登记仓库
- `PUT /api/hololake/knowledge/page` 只接受普通 Markdown、精确 `main`
  基线与已绑定设备会话；服务器用临时 Git index 原子前移裸仓库并返回提交回执
- `本地密钥/**`、路径穿越、非 Markdown、超限内容与过期基线全部失败关闭，回执
  不包含页面内容
  `bingshuo/hololake-knowledge-base` 的当前 `refs/heads/main` 快照，不向手机下发 Forgejo 凭据；
- `/api/hololake/ai/catalog` 只返回可用模型编号；`/execute` 只调用服务器登记的提供商与模型，
  不接受任意 URL、请求头或密钥，响应和回执均不包含服务器密钥。

私密模型登记文件使用 `hololake-ai-providers.example.json` 的结构，真实文件只放在
`/etc/guanghu/secrets/hololake-ai-providers.json`，不得提交到仓库。知识仓库路径、模型
登记文件、session pepper 和会话状态路径由 `authorization.env` 固定；手机不能切换这些路径。

## 企业 GHDR 邮件授权与服务器代签

企业原生布局使用独立的 `native-recovery / sign-native-layout-plan`
工单。该动作必须由京东主控的预登记邮箱完成本次批准；在线 HoloLake
广播面板、旧会话和未记录批准通道的会话都不能替代邮件批准。

批准后，京东只签发最长两分钟、单次使用、精确绑定控制器、目标节点、工单、
布局摘要、资源和代次的 Ed25519 能力票据。广州和新加坡控制器通过出站 HTTPS
轮询取得各自票据，在本机固定用途签名器中完成代签，再把签名结果回送京东。

- 布局私钥与轮询传输私钥分离，均只存在于控制器服务器；
- 客户端、浏览器、Mac、企业目标机和代码仓库都不接收私钥；
- `/api/ghdr/authorizer-public-key` 只返回京东授权公钥和指纹；
- `/api/ghdr/controllers/poll` 与 `/result` 只接受控制器传输私钥签过的规范请求；
- `/api/ghdr/sign-layout` 必须收齐两个不同节点、不同故障域的签名才成功；
- 任何端点都不提供私钥导出、任意 URL、任意命令或单签降级。

`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 后，未来安装与更新才走通感桥的结构化工单。