From 0b94a60f5291948178897af23adc7b846eca06c3 Mon Sep 17 00:00:00 2001 From: Local Dev Date: Tue, 8 Sep 2026 12:43:29 +0200 Subject: [PATCH] feat(site/mirrors): docs page for BNS p-record reverse-proxy workaround MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cloudflare's Bot Fight Mode fingerprints Electron's TLS ClientHello and returns HTTP 503 to Theseus regardless of user-agent (verified against whybitcoincash.com). BNS `p` records proxy through Node's undici fetch from the main process, which has a different TLS fingerprint and slips past the check — Theseus renders the upstream under the .bch origin. New /mirrors/ page explains the mechanism, links the relevant code (record-picker.js and main.js serveP), and walks through minting a mirror in Sirius. Ships with an empty featured list; entries populate as .bch names are minted and added to home-cards.json. Also adds a short note on /tools/ pointing at the new page so users hitting a 503 have a discovery path. --- mirrors/index.html | 194 +++++++++++++++++++++++++++++++++++++++++++++ theseus/index.html | 7 ++ 2 files changed, 201 insertions(+) create mode 100644 mirrors/index.html diff --git a/mirrors/index.html b/mirrors/index.html new file mode 100644 index 0000000..b63c8c7 --- /dev/null +++ b/mirrors/index.html @@ -0,0 +1,194 @@ + + + + + +Mirrors — Silent Mode + + + + + + + + + +
+

Reverse-proxy mirrors

+

Some sites — including several of the most-cited pages in the Bitcoin + Cash ecosystem — return HTTP 503 to Theseus, no matter what user-agent it sends. + A short note on why, and how a .bch name gets you through.

+
+ +
+ + +
+

Why Theseus 503s on some sites

+

Cloudflare's Bot Fight Mode (and similar WAF rules) fingerprints the + TLS ClientHello — the cipher list, extensions, and JA3/JA4 hash your browser + sends before any HTTP header is negotiated. Chromium's TLS stack, which Theseus is + built on via Electron, ships with a slightly different fingerprint than desktop + Chrome — enough to trigger the bot heuristic. The server replies with a short + 503 page and the load fails.

+

Stripping Electron/… from the user-agent + doesn't help: the fingerprint sits below HTTP. Disabling HTTP/2 doesn't help either. + From the site's perspective, Theseus is indistinguishable from a scraper.

+
+ + +
+

What a p record does

+

A BCDN name can carry a p record — a + single upstream URL. When Theseus loads a name whose record picker returns + p, it doesn't hand the request to Chromium's network + stack. It hands it to Node's fetch() from the + main process, which uses a different HTTP client (undici) with a completely + different TLS fingerprint — one Cloudflare doesn't flag. The response body comes + back and gets served under the .bch origin.

+

The address bar stays on the BNS name; the upstream never sees your + IP resolve through Cloudflare's browser-bot rules, only through Theseus's outbound + Node fetch. No captcha, no interstitial, no 503.

+

Trade-offs to know: the p path uses the + upstream's own DNS and public certificate authority (unlike ip, + which pins to a raw IP + on-chain TLS fingerprint), and Theseus streams the body + through its own process — so the upstream sees Theseus's outbound IP, not yours. + This is a shared proxy in effect, though only for the one request.

+
+ + +
+

Featured mirrors

+

These names are registered on the Bitcoin Cash chain with a + p record pointing at a Cloudflare-fronted upstream + Theseus can't reach directly. Click any to open it in Theseus (or via + navigate.st if you don't have the browser + installed yet).

+ +
+ +
+ No mirrors published yet. The list will fill in as names are minted + through Sirius. Check back, or mint one yourself — instructions below. +
+
+ +

+ See a site missing? If a Cloudflare-fronted page you care about is + unreachable from Theseus, either mint a p record for + it yourself, or open an issue on + the Theseus repo and + we'll add it to the featured list once it's on chain. +

+
+ + +
+

Mint a mirror yourself

+

Registration costs a few sats of BCH. Theseus 0.3.14+ ships with the + Aegis wallet — the wallet the Sirius UI signs against — so this is a couple + of clicks once your wallet has a small balance.

+ +
+
+
1
+
Open sirius.x in Theseus and search + for the label you want. Pick a .bch TLD if the site is + BCH-related; other registered TLDs work too. Mint the name.
+
+
+
2
+
Once minted, open the name's record editor and add: +
p: "https://the-original-upstream.example/" +
The trailing slash matters — anything in the path is used as a prefix + for every request.
+
+
+
3
+
Sign the record change. Wait one confirmation. The record is live + as soon as the next Theseus resolve fetches the beacon.
+
+
+
4
+
Test: type yourname.bch in Theseus's address + bar. If the upstream returns 200, Theseus renders it under your name. Send us + the name and we'll add it to the featured list.
+
+
+ +
+ Be honest about what a mirror is. The upstream is unchanged — the site + operator hasn't consented to being served under your BNS name, and doesn't get + paid for any traffic that lands through the mirror. This is a workaround for a + reachability problem, not a rehosting. If you'd rather leave the mirror to us, + open an issue and we'll consider whether it's canonical enough to include. +
+
+ + +
+

The relevant code

+

For anyone curious about the exact mechanism:

+
    +
  • Record priority — pickRecord() in Argus: + h > s3 > ip > p > u at the apex, and + subdomain inheritance never picks p. Theseus + carries an inline copy to keep in step.
    • +
  • Theseus proxy pipeline — theseus/main.js, + the serveP closure inside serveBns(). + Uses fetch(target, { redirect: "manual" }) + from the main process, which is Node's undici — a different TLS stack from + Chromium's, and the reason the fingerprint check doesn't fire.
    • +
+
+ +
+ + + + + diff --git a/theseus/index.html b/theseus/index.html index d146d22..4c17701 100644 --- a/theseus/index.html +++ b/theseus/index.html @@ -189,6 +189,13 @@ +
Some sites 503 in Theseus. + Cloudflare's Bot Fight Mode fingerprints Electron's TLS handshake and blocks it, no + matter what user-agent Theseus sends. The workaround is a BCDN + p record that reverse-proxies the site through Node's + HTTP stack — see Reverse-proxy mirrors for the featured + list and how to mint your own.
+
Not in a store. Neither version is on the Microsoft Store, Google Play or the App Store. Distributing there requires a legal identity and the store's permission, the two things this project exists to do without. You will have