# P1-06 云端落地（TLS + 按设备凭证 + 任务白名单 + 审计）

日期：2026-10-17 ｜ 状态：本地实现与测试全部完成；服务器部署待执行（见 §5）

## 1. 交付物

| 文件 | 作用 |
|---|---|
| [cloud/server/auth.py](file:///d:/NX_AI/cloud/server/auth.py) | HMAC-SHA256 签名验证 + nonce 防重放（时间窗 ±300s） |
| [cloud/server/store.py](file:///d:/NX_AI/cloud/server/store.py) | SQLite 三表（devices/jobs/audit），单连接+锁，审计只落参数摘要 |
| [cloud/server/server.py](file:///d:/NX_AI/cloud/server/server.py) | 9 端点 HTTP 服务（stdlib ThreadingHTTPServer），白名单闸门，TLS 可选 |
| [cloud/client/worker.py](file:///d:/NX_AI/cloud/client/worker.py) | 轮询 worker：签名请求 / 白名单执行 / TLS 指纹锚定 / 常驻或单轮 |
| [tests/test_p1_06_cloud.py](file:///d:/NX_AI/tests/test_p1_06_cloud.py) | 40 项集成测试（真实端口），含卡面强制四条安全用例 |
| [tools/make_selfsigned_cert.py](file:///d:/NX_AI/tools/make_selfsigned_cert.py) | 自签证书生成（纯文件输出，含指纹文件） |
| [tools/deploy_p1_06.py](file:///d:/NX_AI/tools/deploy_p1_06.py) | 部署器：DryRun 默认，--apply 经 SSH/WMI 落地（relay 修复版同步） |

## 2. 安全设计（红线落地）

- **每设备独立密钥**：注册（管理密钥签名）→ 发 `device_id` + 一次性激活码 →
  激活换 `device_key`（用后即焚）。全程无共享 token。
- **HMAC 签名**：`method\npath\nts\nnonce\nsha256(body)`，常数时间比较；
  时间窗外（±300s）作废；nonce 一次性（防重放）。
- **任务白名单**：服务端只入队/下发 `TASK_WHITELIST` 里的命名任务类型 +
  结构化参数；客户端映射到本地固定函数；**下发永远不是命令**。
- **红线扫描**（ast 级，tests D1 守护）：cloud 全目录禁止命令执行通道
  （subprocess/Popen/system 标识符 + 命令拼接痕迹字符串）。注释不算数。
- **审计**：每次调用落 `设备/动作/参数摘要(sha256[:16])/结果`，**不落原文**，
  管理端点可导出。
- **TLS**：默认要求；https 必须配 `tls_fingerprint`（证书 DER 的 sha256 作信任锚，
  适配自签）；明文 http 仅允许 127.0.0.1/localhost；`allow_insecure_tls` 需显式开启。

## 3. 技术栈偏离说明（经用户决策）

任务卡原文写 FastAPI + pytest + httpx；本机/服务器均未安装且装软件属人工清单，
服务器内存紧张（2GB，可用 0.37GB）依赖脆弱。**改为 stdlib http.server + hmac +
urllib 零依赖实现**，测试用项目统一轻量框架 + urllib 打真实端口（比 TestClient 更真实）。
与服务器上已稳定运行的 relay v2 同路线。

## 4. 端点与端口约定

| 端点 | 鉴权 | 说明 |
|---|---|---|
| GET /healthz（别名 /v1/healthz） | 无 | 健康检查（别名适配反代前缀） |
| POST /v1/devices/register | 管理密钥 | 建设备 → id + 一次性激活码 |
| POST /v1/devices/activate | 一次性激活码 | 换设备密钥（一次有效） |
| POST /v1/devices/heartbeat | 设备密钥 | 能力位+NX版本，回待处理数 |
| GET /v1/jobs/poll | 设备密钥 | 原子认领最旧命名任务 |
| POST /v1/jobs/result | 设备密钥 | 结果+产物sha256+耗时（校验归属） |
| POST /v1/admin/enqueue | 管理密钥 | 入队（非白名单→400 task_not_allowed） |
| POST /v1/admin/revoke | 管理密钥 | 吊销设备 |
| GET /v1/admin/audit | 管理密钥 | 导出审计 |

本地默认 127.0.0.1:8765。生产路径规划：nginx `location /nxai/` →
`proxy_pass http://127.0.0.1:8765/v1/`（剥前缀），worker `base_url=https://ldeh.asia/nxai`。
`/api/v1` 保持归 Agent OS 后端（8000），互不干扰。

## 5. 部署步骤（待执行）

```powershell
# 1) 预演（只读，不改服务器）
python D:\NX_AI\tools\deploy_p1_06.py --dry-run
# 2) 取 ldeh.asia 证书指纹（填入 config\cloud.json worker.tls_fingerprint）
python D:\NX_AI\tools\deploy_p1_06.py --show-fingerprint
# 3) 真实部署（你自己的窗口里，密码不落盘；含 relay 修复版同步 + WMI 重启）
$env:NXAI_CLOUD_SSH_PWD='你的SSH密码'
python D:\NX_AI\tools\deploy_p1_06.py --apply
# 4) 注册设备并填入 worker 段（管理密钥在服务器 C:\nxai-cloud\app\data\admin_key.txt）
# 5) python D:\NX_AI\cloud\client\worker.py --once   # 首轮人工验证
```

## 6. 验收结果（本机，2026-10-17）

- 卡面四条安全用例真实通过：无签名 401 / 重放 401 / 非白名单 400 / 吊销后 401
- 集成测试 40/40 PASSED（真实端口；TLS 自签+指纹 D7~D9 全过）
- auth 9/9、store 15/15、server --self-test 12/12、worker 8/8、证书工具 PASSED、部署器 7/7
- 门禁：语法 64 .py 0/0；评测 13/13、漂移 0；既有测试 24/24、28/28、35/35 无退化
- 代码里搜不到 shell=True / cmd /c / subprocess / os.system / Popen（ast 级扫描）