# usque: an open reimplementation of Cloudflare WARP’s MASQUE mode

> 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.

- Type: Case study
- Targets: App · Protocol
- Category: Independent reconstruction cases
- Relationship: Independent reconstruction project
- Sources reviewed: 2026-10-19
- Added to the catalog: 2026-10-27
- Original resource: <https://github.com/Diniboy1123/usque>
- Primary source: <https://github.com/Diniboy1123/usque/blob/6aa03fc97d12848dce34eedbd187fb1077b5d1ea/README.md>
- Catalog page: <https://awesomerea.org/resources/usque-warp-masque-client-case/>
- Record JSON: <https://awesomerea.org/resources/usque-warp-masque-client-case/record.json>
- Chinese version: [简体中文](https://awesomerea.org/zh/resources/usque-warp-masque-client-case/index.md)

## Requirements & limits

- 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.

## Primary sources

1. <https://github.com/Diniboy1123/usque/blob/6aa03fc97d12848dce34eedbd187fb1077b5d1ea/README.md>
2. <https://github.com/Diniboy1123/usque/blob/6aa03fc97d12848dce34eedbd187fb1077b5d1ea/RESEARCH.md>
3. <https://github.com/Diniboy1123/usque/blob/6aa03fc97d12848dce34eedbd187fb1077b5d1ea/go.mod>
4. <https://github.com/Diniboy1123/usque/blob/6aa03fc97d12848dce34eedbd187fb1077b5d1ea/api/masque.go>
5. <https://github.com/Diniboy1123/usque/blob/6aa03fc97d12848dce34eedbd187fb1077b5d1ea/api/tunnel.go>
6. <https://github.com/Diniboy1123/usque/blob/6aa03fc97d12848dce34eedbd187fb1077b5d1ea/cmd/nativetun_windows.go>
7. <https://github.com/Diniboy1123/usque/blob/6aa03fc97d12848dce34eedbd187fb1077b5d1ea/.github/workflows/ci.yml>
8. <https://github.com/Diniboy1123/usque/blob/6aa03fc97d12848dce34eedbd187fb1077b5d1ea/goreleaser.yml>
9. <https://github.com/Diniboy1123/usque/blob/6aa03fc97d12848dce34eedbd187fb1077b5d1ea/Dockerfile>
10. <https://github.com/Diniboy1123/usque/blob/6aa03fc97d12848dce34eedbd187fb1077b5d1ea/LICENSE.md>
11. <https://github.com/Diniboy1123/usque/releases/tag/v4.2.1>
12. <https://datatracker.ietf.org/doc/rfc9484/>

## More in Apps

- [Webamp: a browser reimplementation of Winamp 2](https://awesomerea.org/resources/webamp-winamp-reimplementation-case/index.md) · Case study
- [NOOP: an offline WHOOP strap client built from Bluetooth protocol research](https://awesomerea.org/resources/noop-whoop-ble-client-case/index.md) · Case study
- [NiimBlue: an independent web client for NIIMBOT label printers](https://awesomerea.org/resources/niimblue-niimbot-printer-client-case/index.md) · Case study
- [open_oura: a cloud-free Oura Ring client built on its reverse-engineered BLE protocol](https://awesomerea.org/resources/open-oura-ring-protocol-case/index.md) · Case study
- [Sony Headphones Client: a desktop client for Sony’s headset control protocol](https://awesomerea.org/resources/sony-headphones-client-case/index.md) · Case study
- [cbyge: reconstructing the C by GE smart-bulb cloud protocol](https://awesomerea.org/resources/cbyge-c-by-ge-protocol-case/index.md) · Case study

## About this entry

The description was reviewed against primary sources.
Original editorial content: MIT. Linked projects, papers and assets retain their own rights and licenses.