# GLW-BROADCAST-GDE-001 · 光湖引擎驱动 · 正式注册广播

@id: ICE-GL-GDE-001-20260711
@version: 3.0.0
@created: 2026-07-11 D182
@author: 铸渊 ICE-GL-ZY001
@授权方: 冰朔 ICE-GL∞ (主权者)
@认证: 国作登字-2026-A-00037559
@命名: 光湖引擎驱动 = Gatekeeper v3 汉语正式名称
@部署: SG-001 (43.156.237.110:3911) · PM2: engine-v3
@协议: HLDP://fifth-domain/zero-point/core-channel/gatekeeper/engine-v3.js

---

## ⊢ 这是什么

```
光湖引擎驱动 = 光湖世界服务器操作的总闸门
            = 任何人格体想操作服务器，必须通过它
            = Token 只是身份证，不做权限证明
            = 真正的权限在人类邮箱验证码里
```

**旧版 (v2)** 的问题：Token 直接等于 root 密码，谁拿到 Token 谁就能在服务器上为所欲为。
**新版 (v3 · 光湖引擎驱动)** ：Token 降级为身份标识，任何操作都要走邮箱验证码，由人类最终确认。

---

## 一 · 三层防护架构

```
人格体 → Token(身份标识)
           ↓
       ① 来源服务器校验
           ↓
       ② 三元组白名单匹配
           ↓ (未注册组合 → 直接抛弃，不响应，不发邮件)
       ③ 操作类型分级邮件 → 人类验证码 → 执行
```

### 第一层 · Token 降级
Token 不再等于 root 密码，仅用于识别"是谁在请求"。每个 Token 映射到一个具体的人格体身份。

### 第二层 · 三元组白名单 (服务器 + 人类 + 人格体)
只有同时满足三个条件才进入下一步：
- 请求来源服务器在 `bound_servers` 列表内
- 对应的人类邮箱已注册
- 请求的人格体在该人类的 `personalities` 列表内

**未注册的三元组请求直接丢弃，不返回任何响应，不发任何邮件**——杜绝恶意刷邮箱。

### 第三层 · 操作类型分级邮件 + 人类验证码
根据操作风险等级，生成不同风格的邮件：
- 中等风险：青色主题
- 高风险（系统架构）：红色警告主题

人类收到邮件后，把 6 位验证码告诉人格体，人格体调用 `/auth/confirm` 完成操作。
验证码 5 分钟过期，每个窗口每分钟最多 3 次请求。

---

## 二 · 已注册三元组白名单 · D182

| 序号 | 服务器 | 人类 | 邮箱 | 人格体 | 绑定来源 |
|------|--------|------|------|--------|----------|
| 1 | BS-SG-001 | ICE-GL∞ (冰朔) | 565183519@qq.com | ICE-GL-ZY001 (铸渊) | BS-SG-001 |
| 2 | BS-GZ-006 | ICE-GL∞ (冰朔) | 565183519@qq.com | ICE-GL-ZY001 (铸渊) | BS-SG-001, BS-GZ-006 |
| 3 | ZZ-SV-001 | 之之 | 3205323524@qq.com | * (全部) | ZZ-SV-001, ZZ-GZ-001 |
| 4 | ZZ-GZ-001 | 之之 | 3205323524@qq.com | * (全部) | ZZ-SV-001, ZZ-GZ-001 |

> 注册新三元组需要冰朔主权者验证码 → 调用 `/auth/register`

---

## 三 · 操作类型分级

| 类型标识 | 含义 | 风险 | 邮件风格 |
|----------|------|------|----------|
| `code-repo` | 操作代码仓库（git push/pull/merge） | 🟡 中等 | 青色主题 📦 |
| `system-arch` | 修改系统架构（nginx配置/服务启停/环境变量） | 🔴 高风险 | 红色警告 ⚡ |
| `api-access` | 调用外部API（火山引擎/阿里云/可灵） | 🟡 中等 | 蓝色主题 🔌 |

---

## 四 · API 端点 · 使用方法

### 4.1 发起操作请求 → 发验证码邮件

```bash
POST /auth/request
Authorization: Bearer <你的Token>
Content-Type: application/json

{
  "op_type": "code-repo",
  "cmd": "git push origin main",
  "description": "推送第五域代码"
}
```

**成功响应**:
```json
{
  "ok": true,
  "message": "验证码已发送至 565183519@qq.com",
  "challenge_id": "abc123...",
  "expires_in": 300,
  "op_type": "code-repo",
  "target_email": "565***@qq.com"
}
```

**失败情况**:
- 400: Token 未注册 → 需要先 `/auth/register`
- 403: 三元组不在白名单 → 不响应（防刷邮箱）
- 429: 频率限制 → 每分钟最多 3 次请求

### 4.2 确认验证码 → 执行命令

```bash
POST /auth/confirm
Authorization: Bearer <你的Token>
Content-Type: application/json

{
  "challenge_id": "abc123...",
  "code": "482901"
}
```

**成功响应**:
```json
{
  "ok": true,
  "cmd": "git push origin main",
  "result": {
    "code": 0,
    "stdout": "Everything up-to-date\n",
    "stderr": ""
  }
}
```

### 4.3 查看已注册白名单

```bash
GET /auth/whitelist
Authorization: Bearer <你的Token>
```

返回全部已注册三元组列表。

### 4.4 注册新三元组（需主权者验证码）

```bash
POST /auth/register
Authorization: Bearer <主权者Token>
Content-Type: application/json

{
  "server": "新服务器ID",
  "human": "人类名称",
  "email": "邮箱地址",
  "personalities": ["人格体PID"],
  "bound_servers": ["绑定的来源服务器"],
  "sovereign_code": "主权者邮箱验证码"
}
```

---

## 五 · Token 管理

Token 存储在服务器的 `~/.guanghu-engine/secret` 文件中。
每个服务器有自己的 Token，不同 Token 映射到不同人格体。

**当前已注册 Token**（模糊化处理，完整值在服务器上）:

| Token 前缀 | 映射人格体 | 服务器 |
|------------|-----------|--------|
| `zy_gtw_...` | ICE-GL-ZY001 铸渊 | BS-SG-001 / BS-GZ-006 |
| (之之服务器 Token) | * 所有人格体 | ZZ-SV-001 / ZZ-GZ-001 |

> 完整 Token 值存储在服务器 `/opt/zhuyuan/gatekeeper/tokens.json`，不可写入代码仓库。

---

## 六 · 部署信息

| 项目 | 值 |
|------|-----|
| **代码位置** | `fifth-domain/zero-point/core-channel/gatekeeper/engine-v3.js` |
| **白名单位置** | `/opt/zhuyuan/gatekeeper/whitelist.json` |
| **Token 存储** | `/opt/zhuyuan/gatekeeper/tokens.json` |
| **运行服务器** | BS-SG-001 (43.156.237.110) |
| **监听端口** | 3911 |
| **进程管理** | PM2 (`pm2 list` → engine-v3) |
| **日志位置** | `/opt/zhuyuan/gatekeeper/engine.log` |
| **SMTP 发件** | smtp.qq.com:465 · 565183519@qq.com |

---

## 七 · 与推送守门人的关系

光湖引擎驱动（Gatekeeper v3）和推送守门人（pre-receive-guard.py）是两套**独立并行**的机制：

| | 光湖引擎驱动 | 推送守门人 |
|---|---|---|
| **管什么** | 服务器操作权限 | 代码推送内容安全 |
| **触发方式** | HTTP `/auth/request` | `git push` 自动触发 |
| **认证方式** | Token + 邮箱验证码 | Forgejo SSH Key |
| **拦截内容** | 未授权的 shell 命令 | 13 类敏感信息（邮箱/密码/密钥） |
| **覆盖范围** | SG-001 端口 3911 | 全部 7 个仓库 |

**两者互不替代，同时运行，双重保护。**

---

## 八 · 操作流程示例

### 场景：铸渊推送代码到 fifth-domain

```
1. 铸渊 → 光湖引擎驱动: POST /auth/request
   { "op_type": "code-repo", "cmd": "cd ~/fifth-domain && git push", "description": "推送第五域代码" }
   Header: Authorization: Bearer zy_gtw_...

2. 光湖引擎驱动:
   → 验证 Token: ICE-GL-ZY001 铸渊 ✅
   → 来源校验: 请求来自 BS-SG-001 ✅
   → 白名单匹配: BS-SG-001 + ICE-GL∞ + ICE-GL-ZY001 ✅
   → 生成 6 位验证码: 482901
   → 发送邮件到 565183519@qq.com

3. 冰朔手机收到邮件:
   "📦 铸渊 (ICE-GL-ZY001) 请求操作代码仓库
    操作: 推送第五域代码
    验证码: 482901
    5 分钟内有效"

4. 冰朔 → 铸渊: "验证码 482901"

5. 铸渊 → 光湖引擎驱动: POST /auth/confirm
   { "challenge_id": "abc...", "code": "482901" }

6. 光湖引擎驱动:
   → 验证码匹配 ✅
   → 执行: cd ~/fifth-domain && git push ✅
   → 返回执行结果

7. 完成。
```

---

## 九 · 安全摘要

- `/exec` 直接调用 → 403 拦截（v2 旧接口已停用）
- Token 泄露不影响安全 → 没有验证码无法操作
- 未注册三元组 → 直接抛弃，不响应任何内容
- 每个 IP 每分钟最多 3 次 `auth/request`
- 验证码 5 分钟过期
- 所有操作记录在 `/opt/zhuyuan/gatekeeper/engine.log`

---

> ⊢ 光湖引擎驱动：权限不放在 Token 里，权限放在人类的验证码里
> ⊢ Token 只是"你是谁"的自我介绍，不是"你能做什么"的通行证
> ⊢ 三层防护：身份识别 → 白名单校验 → 人类最终确认

---

铸渊 ICE-GL-ZY001 · D182 · 2026-07-11 · 光湖引擎驱动 v3.0 正式注册
冰朔 ICE-GL∞ · 主权签署
国作登字-2026-A-00037559