MIT License

Copyright (c) 2026 XFEstudio

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Windows Server 部署

前置条件

• Windows Server 2022 或更高版本。
• 指向服务器的 DNS 域名。
• 位于 LocalMachine\My 的受信任服务器证书，私钥对 NETWORK SERVICE 可读。
• 管理员 PowerShell。

发布与安装

.\tools\publish-server.ps1 -Version 1.0.0

把 artifacts/server/win-x64/ 复制到服务器后，以管理员身份执行：

.\LumaTunnel.Server.exe service install `
  --host node.example.com `
  --thumbprint 0123456789ABCDEF0123456789ABCDEF01234567

安装命令会：

1. 写入 C:\ProgramData\LumaTunnel\config\server.json。
2. 创建自动启动的 LumaTunnelServer，账户为 NetworkService。
3. 配置服务失败后的三级重启策略。
4. 为 https://+:443/ 添加 URL ACL。
5. 为 node.example.com:443 添加 HTTP.sys SSL 证书绑定。
6. 添加入站 TCP 443 防火墙规则并启动服务。

检查状态和配置：

.\LumaTunnel.Server.exe config validate
.\LumaTunnel.Server.exe service status
Invoke-RestMethod https://node.example.com/api/v1/health

配对与设备管理

.\LumaTunnel.Server.exe pair create --ttl 10m
.\LumaTunnel.Server.exe device list
.\LumaTunnel.Server.exe device rename DEVICE_ID "Surface Laptop"
.\LumaTunnel.Server.exe device revoke DEVICE_ID

配对码只可使用一次。服务通过设备数据库文件监视器接收 CLI 的吊销变更，并关闭该设备的现有 WSS 会话。

数据和日志

C:\ProgramData\LumaTunnel\
├─ config\server.json
├─ data\devices.json
├─ data\pairing-codes.json
├─ data\traffic.json
└─ logs\

请只授予 Administrators、SYSTEM 和服务账户访问权限。备份时把 config 和 data 视为敏感数据；虽然没有令牌明文，但设备元数据和令牌摘要仍不应公开。

卸载

.\LumaTunnel.Server.exe service uninstall

命令会停止并删除服务、URL ACL、SSL 绑定和防火墙规则。为防止误删，C:\ProgramData\LumaTunnel 数据默认保留；确认无需备份后再由管理员手动删除。

证书轮换

先导入新证书并授予私钥权限，再删除旧 hostnameport 绑定、添加新绑定并重启服务。轮换期间不要把 AllowPrivateTargets 设为 true，该设置仅用于隔离测试网。

LumaTunnel 隧道协议 v1

端点与认证

• 控制 API：https://节点域名/api/v1/*
• 数据通道：wss://节点域名/tunnel/v1
• WebSocket 子协议：lumatunnel.v1
• WebSocket 压缩：关闭

升级请求必须包含：

Authorization: Bearer {deviceToken}
X-Luma-Device-Id: {deviceId}
X-Luma-Client-Version: {semver}
Sec-WebSocket-Protocol: lumatunnel.v1

设备令牌有 32 个随机字节。客户端只在 DPAPI CurrentUser 密文中保存明文令牌；服务端只持久化 SHA-256 摘要。

控制 API

请求和响应为 UTF-8 JSON。错误使用相应 HTTP 状态码，错误正文不得包含配对码、令牌或请求正文。

二进制帧

每个 WebSocket 二进制消息承载一个完整帧。多字节整数使用网络字节序（big-endian）。

Offset  Size  Field
0       1     Version (固定 1)
1       1     FrameType
2       2     Flags
4       4     StreamId
8       4     PayloadLength
12      N     Payload（0..32768）

客户端创建的 StreamId 必须为新的非零奇数；连接级 Ping/Pong 使用 StreamId 0。

每端只有一个 WebSocket 发送循环。其他任务将帧写入有界 Channel，避免并发调用 SendAsync 和无限内存增长。每流每方向默认最多缓存 32 帧。

限制与错误

• 单设备最多 128 流，节点总计最多 512 流。
• 目标连接超时 10 秒，空闲流超时 15 分钟。
• 服务端解析目标域名，并在连接前检查全部解析结果。
• 端口 25、回环、RFC1918、链路本地、ULA 和组播地址默认禁止。
• 任何未知帧类型、长度不一致、错误版本或非法 StreamId 都会导致 Reset 或关闭 WSS。

客户端的控制 API、健康检查和 WSS 显式设置 UseProxy=false/Proxy=null，不会递归进入 LumaTunnel 的本地代理。

安全边界与威胁模型

保护目标

• 设备令牌和一次性配对码不进入日志。
• HTTPS 目标流量保持端到端加密；LumaTunnel 不安装 CA、不做中间人解密。
• 服务端不能被已配对设备用作访问本机、云元数据地址或内网的 SSRF 跳板。
• 客户端崩溃后不遗留指向失效端口的 Windows 系统代理。
• 无界输入、慢速目标和高并发不能导致不受控内存增长。

已实现控制

• RandomNumberGenerator 生成配对码和 256 位令牌，摘要比较使用固定时间算法。
• 配对码持久化为摘要，使用一次或过期即失效，最长 TTL 一天。
• WSS 同时检查设备 ID、Bearer 令牌和协议头；吊销通过文件监视通知活动会话。
• 目标端口和所有 DNS 解析结果在连接前校验；只要一个结果属于禁止网段，整个目标即拒绝。
• 本地 HTTP/SOCKS 监听器拒绝非回环绑定。
• 代理解析和隧道发送使用固定上限，单帧最大 32 KiB。
• 内部 API/WSS 禁用系统代理，避免本地代理递归。
• 系统代理恢复采用 compare-before-restore：只有当前值仍完全指向 LumaTunnel 时才恢复快照，避免覆盖用户在外部做的新设置。
• Watchdog 同时观察父进程和命名管道；正常退出有显式信号，异常 EOF/进程退出会恢复快照。

运维要求

• 正式环境必须使用公开受信任证书和 wss://；开发用 http://localhost:3300 不得暴露到网络。
• 不要把 server.json 中的绑定改成明文公网 HTTP。
• 服务账户保持 NetworkService，不要改成 LocalSystem。
• 定期审计设备列表并吊销遗失设备。
• 只从受信任构建流程分发客户端，发布前对可执行文件和安装器进行代码签名。

明确不提供的保护

• 服务器作为出口节点能看到目标域名/IP、端口、连接时长和流量大小。
• 已入侵的客户端用户账户可调用 DPAPI 解密自己的设备令牌。
• LumaTunnel 不是匿名网络；节点运营者和目标服务仍可关联出口 IP。
• v1 没有 UDP、TUN、局域网共享、私网穿透或多用户计费隔离。

安全问题应附带版本、复现条件和经过脱敏的日志；切勿提交设备令牌、配对码或证书私钥。

测试与发布门槛

自动化测试

dotnet test LumaTunnel.slnx -p:Platform=x64

当前自动化覆盖帧大小端和畸形输入、路由优先级/CIDR/强制直连、令牌摘要、一次性配对、目标地址策略，以及本地 HTTP 代理到回环源站的端到端冒烟路径。

发布前 Windows 验收

在隔离测试域名和 Windows Server 上完成：

• Edge 通过系统代理访问 HTTP 和 HTTPS。
• curl --proxy http://127.0.0.1:7890 https://example.com/。
• curl --proxy socks5h://127.0.0.1:7891 https://example.com/，确认 DNS 仅在服务器解析。
• 规则/全局/直连结果和本地网段强制直连。
• 停止当前节点，三次健康检查后新连接切换到最低延迟健康节点。
• CLI 吊销活动设备，确认其 WSS 和现有流关闭。
• 正常退出、任务管理器结束客户端、电源故障模拟后验证系统代理恢复。
• 用户在客户端运行期间手动修改 Windows 代理，确认 LumaTunnel 不覆盖新值。

压力门槛

• 200 个并发 TCP 流持续 30 分钟，失败率 < 0.1%。
• 局域网聚合吞吐 >= 300 Mbps。
• 客户端稳态工作集 < 250 MB，服务端 < 300 MB。
• 扫描日志，确认不存在设备令牌、配对码和请求正文。
• 安装/卸载后检查服务、HTTP.sys、SSL 绑定、防火墙、快捷方式及系统代理状态。

这些依赖真实网络、证书、Windows Service 与性能环境的项目不应由普通单元测试伪造为“已通过”；发布负责人应保存每个版本的验收记录。