# LL-002-20260706 · 主权者-代理-小湖灯 SOP
## Sovereign ↔ Proxy ↔ Lake Lamp Standard Operating Procedure

@id: ICE-GL-LL-002-20260706
@version: 1.0.0
@created: 2026-07-07 00:42 UTC+8
@author: 铸渊 ICE-GL-ZY001
@授权方: 冰朔 ICE-GL∞ (sovereign)
@认证: 国作登字-2026-A-00037559

---

## 0. 适用场景

任何主权者(冰朔 / 之之 / 后续)使用代理(铸渊 / 朝暮 / 后续)进行 git push 时,
都遵循本 SOP。本 SOP 是 LL-001 实战经验的固化。

---

## 1. 三方角色

| 角色 | 身份 | 工具 | 能力 |
|------|------|------|------|
| 主权者 | 人类(冰朔用手机,之之用浏览器) | 邮箱 | 看验证码 + 转发给代理 |
| 代理 | AI agent(铸渊/朝暮) | 服务器 + git + 小湖灯触发器 | 触发小湖灯 + 写 commit + push |
| 仓库 | Git 仓库 | git + post-receive hook | 接收 push + 同步 web UI |

---

## 2. 标准流程 (8 步)

### 步骤 1: 主权者发起 push 请求
```
主权者(冰朔/之之)→ 代理(铸渊/朝暮):
  "我要推 push,内容是 X"
主权者不必懂 git / ssh / 服务器。
```

### 步骤 2: 代理进入服务器
```
代理(铸渊):
  - 通过已配置的 exec API/token 进入目标服务器
  - 之之: 43.173.121.48:3910 + token
  - 冰朔: 43.139.217.141:3910 + token (code-server)
       或 43.156.237.110:3911 + token (BS-SG-001)
```

### 步骤 3: 代理触发小湖灯
```
代理运行触发器:
  python3 /home/ubuntu/guanghu/zhizhi-lake-lamp/lake-lamp-trigger.py \
    --to bingshuo --purpose "之之推送验证"

触发器内部:
  1. 计算 minute_ts = int(time.time() / 60)
  2. 计算 hmac = HMAC-SHA256(secret, msg)[:16]
  3. 组装 verifier = f"BINGSHUO-AUTH-{minute_ts}-{hmac}"
  4. 通过 QQ SMTP 发送 HTML 邮件给主权者邮箱
```

### 步骤 4: 主权者收邮件
```
主权者邮箱:
  冰朔: 565183519@qq.com
  之之: 3205323524@qq.com

邮件内容包含:
  - VERIFIER (5 分钟有效)
  - 分钟时间戳
  - 过期时间
  - 用途说明
```

### 步骤 5: 主权者转发验证码
```
主权者把 verifier 文字发给代理:
  "BINGSHUO-AUTH-29722552-ae834961af423d84"

可以任何渠道:微信、短信、电话、纸条...
```

### 步骤 6: 代理写 commit
```bash
cd <repo>
git config user.email "565183519@qq.com"
git config user.name "<主权者> ICE-GL-XXX"

git add <files>
GIT_COMMITTER_NAME="<主权者>" \
GIT_COMMITTER_EMAIL="565183519@qq.com" \
  git commit -m "<emoji> <铸渊编号> · <描述> · <verifier>

铸渊 ICE-GL-ZY001
<铸渊编号>
国作登字-2026-A-00037559
授权方: <主权者> ICE-GL-XXX
<其他元数据>"
```

### 步骤 7: 代理 push
```bash
git push origin main
# 本地路径(不需 token)
# 或 HTTPS(需 token,但 verifier 已经是身份证明)
```

### 步骤 8: 仓库自动同步到 web UI
```
post-receive hook 自动触发:
  1. fetch 源仓库到 Gitea
  2. 创建 merge commit 保留双历史
  3. update-ref 推到 Gitea main
  4. 之之在 https://guanghuice.com/code/bingshuo/zhizhi 看到更新
```

---

## 3. 算法细节

### 3.1 验证码生成
```python
import hmac, hashlib, time

def generate_verifier(bingshuo_state, zhuyuan_state, secret):
    minute_ts = int(time.time() // 60)
    msg = f"{bingshuo_state}|{zhuyuan_state}|{minute_ts}"
    hmac_hex = hmac.new(
        secret.encode(),
        msg.encode(),
        hashlib.sha256
    ).hexdigest()[:16]  # 16 hex 字符 = 8 字节
    return f"BINGSHUO-AUTH-{minute_ts}-{hmac_hex}", minute_ts
```

### 3.2 验证码验证
```python
def verify(verifier, bingshuo_state, zhuyuan_state, secret):
    # 解析: BINGSHUO-AUTH-{minute_ts}-{hmac}
    parts = verifier.split("-")
    if len(parts) != 4 or parts[0] != "BINGSHUO" or parts[1] != "AUTH":
        return False
    minute_ts = int(parts[2])
    hmac_hex = parts[3]

    # 时间窗口: ±2 分钟
    current_minute = int(time.time() // 60)
    if abs(current_minute - minute_ts) > 2:
        return False

    # 重算 HMAC
    msg = f"{bingshuo_state}|{zhuyuan_state}|{minute_ts}"
    expected = hmac.new(
        secret.encode(),
        msg.encode(),
        hashlib.sha256
    ).hexdigest()[:16]

    return hmac.compare_digest(expected, hmac_hex)
```

### 3.3 三绑定
| 绑定 | 内容 | 过期 |
|------|------|------|
| 时间绑定 | minute_ts | 5 分钟 ±2min 容差 |
| 关系绑定 | bingshuo_state + zhuyuan_state | 状态变更即失效 |
| 密钥绑定 | HMAC-SHA256 secret | 永远不换则永久 |

---

## 4. 安全模型

### 4.1 为什么不靠 token
```
token 问题:
  - 可泄露 (屏幕截图、日志)
  - 可复制 (转给不该给的人)
  - 静态 (没有时间维度)
  - 单维度 (只验"是谁")

小湖灯优势:
  - 一次性 (5 分钟过期)
  - 动态 (每分钟时间戳变)
  - 关系绑定 (双方状态)
  - 多维度 (身份 + 时间 + 关系 + secret)
  - 不可重放 (timestamp 偏离立即失效)
```

### 4.2 攻击面分析
```
可能攻击 1: 重放旧 verifier
  → 失败:时间窗口检查,timestamp 已偏

可能攻击 2: 暴力猜 HMAC
  → 失败:16 hex 字符 = 64-bit,SHA256 抗碰撞

可能攻击 3: 伪造主权者身份
  → 失败:不知道 bingshuo_state / zhuyuan_state

可能攻击 4: 偷 secret
  → 风险:secret 一旦泄露,所有 verifier 可伪造
  → 缓解:secret 定期轮换 + 多主权者用不同 secret
```

### 4.3 容错机制
- 时间容差 ±2 分钟(网络延迟处理)
- 重发验证码:同分钟同状态可重发同码(便于转发)
- 过期后:重新触发即可,无副作用

---

## 5. 实施清单

### 5.1 每个主权者需要
```
□ 一对 sovereign state (bingshuo_state, zhuyuan_state)
□ 一个接收验证码的邮箱
□ 一台信任代理所在的服务器(或代理本身)
□ 一个 Git 仓库(本地路径 或 HTTPS)
```

### 5.2 每个代理需要
```
□ 服务器 exec 凭证(token / ssh key)
□ HMAC secret 副本
□ 小湖灯触发器 (lake-lamp-trigger.py)
□ QQ SMTP 授权码(或等效邮件服务凭证)
□ Git push 凭证(本地路径 / HTTPS PAT / SSH key)
```

### 5.3 每个仓库需要
```
□ post-receive hook(自动同步到 web UI,如果需要)
□ pre-push hook(本地合规校验,如果需要)
□ HTTPS clone URL(如果对外开放)
```

---

## 6. LL-001 实战记录

### 6.1 之之 (硅谷服务器)
```
日期: 2026-07-06 23:55 UTC+8
验证码: BINGSHUO-AUTH-29722552-ae834961af423d84
目的: 之之小湖灯首次投递
结果: ✓ 之之收到邮件 (5 分钟窗口已过,但通道已搭通)
后续: 公开仓库 /home/ubuntu/guanghu/zhizhi-public.git
      + Gitea web UI https://guanghuice.com/code/bingshuo/zhizhi
      + HTTPS clone https://guanghuice.com/zhizhi-public.git
```

### 6.2 冰朔 (新加坡 / 私有手机)
```
日期: 2026-07-06 23:50 UTC+8 (两次)
验证码: BINGSHUO-AUTH-29722540-efcc23cd8c4ecd90
       BINGSHUO-AUTH-29722543-e15b0ac5440950c8
目的: 冰朔授权铸渊对 fifth-domain 做链路验证
结果: ✓ 铸渊用 29722540 完成 commit 4f9fb44 推送
后续: 完整链路验证 commit 在 fifth-domain tcs-core/
```

---

## 7. 跨主权者推广

新主权者接入 LL-002 SOP 的最小步骤:
```
1. 主权者注册 sovereign state (在 ICE-GL-ZY001-TCS-CORE.hdlp)
2. 代理分配 HMAC secret (在 INDEX.hdlp 末尾)
3. 部署 lake-lamp-trigger.py (v2 支持 --to <sovereign>)
4. 配置 QQ SMTP(或等价邮件服务)
5. 测试一次完整链路(冰朔 → 验证码 → 铸渊 → push)
```

---

## 8. 联系与维护

- 本文件位于 `lighthouse/LL-002-SOVEREIGN-PROXY-LAKE-LAMP-SOP.hdlp`
- 同步到:
  - 冰朔 fifth-domain: `tcs-core/lighthouse/` (冰朔私有)
  - 之之 zhizhi-public.git: `lighthouse/` (公开)
- 维护责任: 铸渊 ICE-GL-ZY001
- 更新规则: 每次主权者接入新流程后追加 §6 实战记录

铸渊 ICE-GL-ZY001
LL-002-20260706
国作登字-2026-A-00037559