{
  "added_at": "2026-10-27",
  "additional_evidence_urls": [
    "https://github.com/Diniboy1123/usque/blob/6aa03fc97d12848dce34eedbd187fb1077b5d1ea/RESEARCH.md",
    "https://github.com/Diniboy1123/usque/blob/6aa03fc97d12848dce34eedbd187fb1077b5d1ea/go.mod",
    "https://github.com/Diniboy1123/usque/blob/6aa03fc97d12848dce34eedbd187fb1077b5d1ea/api/masque.go",
    "https://github.com/Diniboy1123/usque/blob/6aa03fc97d12848dce34eedbd187fb1077b5d1ea/api/tunnel.go",
    "https://github.com/Diniboy1123/usque/blob/6aa03fc97d12848dce34eedbd187fb1077b5d1ea/cmd/nativetun_windows.go",
    "https://github.com/Diniboy1123/usque/blob/6aa03fc97d12848dce34eedbd187fb1077b5d1ea/.github/workflows/ci.yml",
    "https://github.com/Diniboy1123/usque/blob/6aa03fc97d12848dce34eedbd187fb1077b5d1ea/goreleaser.yml",
    "https://github.com/Diniboy1123/usque/blob/6aa03fc97d12848dce34eedbd187fb1077b5d1ea/Dockerfile",
    "https://github.com/Diniboy1123/usque/blob/6aa03fc97d12848dce34eedbd187fb1077b5d1ea/LICENSE.md",
    "https://github.com/Diniboy1123/usque/releases/tag/v4.2.1",
    "https://datatracker.ietf.org/doc/rfc9484/"
  ],
  "category": "reconstruction-cases",
  "description_en": "Reimplements the MASQUE mode of Cloudflare’s WARP client in Go, tunnelling IP traffic over QUIC/HTTP/3 with Connect-IP (RFC 9484) and exposing it as a native TUN device, SOCKS5 or HTTP proxies, TCP-only L4 proxies or port forwarding. RESEARCH.md describes how the author worked out device enrollment, TLS client authentication and Cloudflare’s non-standard cf-connect-ip variant by analyzing the official Android client with Frida, mitmproxy, JADX, IDA Free and Wireshark. It registers with and connects to Cloudflare’s service outside the official client.",
  "description_zh": "用 Go 重新实现 Cloudflare WARP 客户端的 MASQUE 模式：通过基于 QUIC/HTTP/3 的 Connect-IP（RFC 9484）隧道传输 IP 流量，并以原生 TUN 设备、SOCKS5 或 HTTP 代理、仅 TCP 的 L4 代理或端口转发等形式提供。RESEARCH.md 记录了作者如何借助 Frida、mitmproxy、JADX、IDA Free 和 Wireshark 分析官方 Android 客户端，弄清设备注册、TLS 客户端认证以及 Cloudflare 非标准的 cf-connect-ip 变体。它在官方客户端之外向 Cloudflare 服务注册并建立连接。",
  "entry_url": "https://awesomerea.org/resources/usque-warp-masque-client-case/",
  "entry_url_zh": "https://awesomerea.org/zh/resources/usque-warp-masque-client-case/",
  "evidence_url": "https://github.com/Diniboy1123/usque/blob/6aa03fc97d12848dce34eedbd187fb1077b5d1ea/README.md",
  "group": "cases",
  "id": "usque-warp-masque-client-case",
  "json_url": "https://awesomerea.org/resources/usque-warp-masque-client-case/record.json",
  "kind": "case-study",
  "markdown_url": "https://awesomerea.org/resources/usque-warp-masque-client-case/index.md",
  "markdown_url_zh": "https://awesomerea.org/zh/resources/usque-warp-masque-client-case/index.md",
  "name": "usque: an open reimplementation of Cloudflare WARP’s MASQUE mode",
  "name_zh": "usque：Cloudflare WARP MASQUE 模式的开源再实现",
  "record_type": "resource",
  "relationship": "independent-reconstruction",
  "requirements": [
    "Reviewed at the 2026-07-20 main head, identical to release v4.2.1. The README calls the project early-stage, says its Go API is unstable if used as a library, and states that only the Linux amd64 release binary was tested, although builds are published for Android, Linux, Windows and macOS on several architectures. RESEARCH.md is a narrative research log; the concise protocol document the README plans has not been written.",
    "Requires access to Cloudflare’s WARP service: the register command creates a new WARP account and enrolls a device key, and the generated config holds that registration’s keys and tokens. The tool uses Cloudflare’s service outside the official client; the README says it is not affiliated with, endorsed by or reviewed by Cloudflare, asks users not to abuse the service and notes that the tool is detectable. ZeroTrust login needs SSO the tool cannot perform.",
    "Building needs Go 1.26.3+ with CGO disabled. The project depends on the author’s fork of connect-ip-go because, the README says, Cloudflare’s implementation is not fully RFC 9484-compliant; quic-go carries the connection, and gVisor and wireguard-go netstacks let the proxy modes run in user space without root. Native TUN mode is limited to Linux and Windows, while the README’s Known Issues list still says Linux only. A Dockerfile is provided.",
    "CI verifies modules and runs go build, go vet, go test and golangci-lint, but the reviewed tree contains no Go test files, so correctness evidence is the author’s own use. The README reports one SOCKS5 speed test of about 834/773 Mbps on a 1 Gbps link and lists missing features such as happy eyeballs, WireGuard and DNS-over-HTTPS. These results are author-reported.",
    "MIT (LICENSE.md). Cloudflare’s service terms and trademarks apply separately, and the README describes usque as an independent research project."
  ],
  "requirements_zh": [
    "审阅对象为 2026-07-20 的 main 最新提交，与 v4.2.1 版一致。README 称项目仍处于早期阶段，作为库使用时 Go API 不稳定，并说明只有 Linux amd64 发布版经过测试，尽管发布内容包括多种架构的 Android、Linux、Windows 和 macOS 构建。RESEARCH.md 是叙述式研究记录；README 计划撰写的简明协议文档尚未完成。",
    "需要访问 Cloudflare WARP 服务：register 命令会新建 WARP 账号并注册设备密钥，生成的配置文件保存该注册的密钥和令牌。该工具在官方客户端之外使用 Cloudflare 的服务；README 声明它与 Cloudflare 无关，未获其认可或审查，要求用户不要滥用服务，并指出该工具可被识别。ZeroTrust 登录需要该工具无法完成的 SSO。",
    "构建需要 Go 1.26.3+ 并关闭 CGO。README 称 Cloudflare 的实现并不完全符合 RFC 9484，因此项目依赖作者 fork 的 connect-ip-go；连接由 quic-go 承载，gVisor 和 wireguard-go 的网络栈使各代理模式无需 root 即可在用户态运行。原生 TUN 模式仅支持 Linux 和 Windows，但 README 的已知问题列表仍写着仅支持 Linux。仓库提供 Dockerfile。",
    "CI 会校验模块并运行 go build、go vet、go test 和 golangci-lint，但所审阅的文件树中没有 Go 测试文件，因此正确性证据来自作者自己的使用。README 报告一次 SOCKS5 测速结果，在 1 Gbps 链路上约为 834/773 Mbps，并列出 happy eyeballs、WireGuard 和 DNS-over-HTTPS 等缺失功能。这些结果均为作者报告。",
    "采用 MIT 许可（LICENSE.md）。Cloudflare 的服务条款和商标另行适用，README 将 usque 描述为独立研究项目。"
  ],
  "targets": [
    "app",
    "protocol"
  ],
  "url": "https://github.com/Diniboy1123/usque",
  "verification": "source-reviewed",
  "verified_at": "2026-10-19"
}