feat(direct): use mhrv-rs as upstream proxy for Psiphon / xray

Author: dazzling-no-more

README.md

@@ -160,6 +160,8 @@ If something doesn't work:
 
 **ISP blocks `script.google.com` itself.** mhrv-rs has a `direct` mode that uses only the SNI-rewrite tunnel (no Apps Script). Use it once to access `script.google.com` to deploy your script, then switch to apps_script mode. See [direct mode](docs/guide.md#direct-mode).
 
+**I want to use mhrv-rs as Psiphon's (or xray's) upstream proxy.** Run mhrv-rs in `direct` mode and point Psiphon's *upstream proxy* setting at the host:port shown under the Connect button. Unfronted hosts pass through as raw TCP, so Psiphon's bootstrap traffic reaches Psiphon's servers untouched. See [docs/use-as-upstream.md](docs/use-as-upstream.md).
+
 **My Google search shows up without JavaScript.** The Apps Script `User-Agent` is fixed to `Google-Apps-Script` (Google won't let scripts change it), so some sites serve a no-JS fallback. Workaround: add the affected domain to your `hosts` map so it goes through the SNI-rewrite tunnel with your real browser User-Agent. `google.com`, `youtube.com`, `fonts.googleapis.com` are already on this list by default.
 
 **More questions:** [full FAQ in the long guide](docs/guide.md#faq).
@@ -330,6 +332,8 @@ System Settings → Network → Wi-Fi → Details → **Proxies** → هر دو
 
 **ISP خود `script.google.com` را مسدود کرده.** mhrv-rs یک حالت `direct` دارد که فقط از تونل بازنویسی SNI استفاده می‌کند (بدون Apps Script). یک‌بار از این حالت استفاده کن تا به `script.google.com` برسی و اسکریپت را دیپلوی کنی، بعد به حالت apps_script سوئیچ کن. [حالت direct](docs/guide.fa.md#حالت-direct).
 
+**می‌خواهم از mhrv-rs به‌عنوان پروکسی upstream برای Psiphon (یا xray) استفاده کنم.** mhrv-rs را در حالت `direct` اجرا کن و در تنظیمات Psiphon قسمت *upstream proxy* را روی host:port که زیر دکمهٔ Connect نمایش داده می‌شود تنظیم کن. هاست‌هایی که در لیست fronting قرار ندارند به‌صورت raw TCP عبور می‌کنند، پس ترافیک bootstrap سایفون به سرورهای سایفون دست‌نخورده می‌رسد. [docs/use-as-upstream.fa.md](docs/use-as-upstream.fa.md).
+
 **جست‌وجوی گوگلم بدون JavaScript ظاهر می‌شود.** `User-Agent` Apps Script ثابت روی `Google-Apps-Script` است (گوگل نمی‌گذارد اسکریپت‌ها عوضش کنند)، پس بعضی سایت‌ها نسخهٔ بدون JS برمی‌گردانند. راه‌حل: دامنهٔ مورد نظر را به `hosts` اضافه کن تا از تونل بازنویسی SNI با User-Agent واقعی مرورگرت برود. `google.com`، `youtube.com`، `fonts.googleapis.com` به‌طور پیش‌فرض در این لیست‌اند.
 
 **سؤالات بیشتر:** [FAQ کامل در راهنمای بلند](docs/guide.fa.md#سؤالات-رایج).

android/app/src/main/java/com/therealaleph/mhrv/ui/HomeScreen.kt

@@ -337,6 +337,77 @@ fun HomeScreen(
                 )
             }
 
+            // Upstream-proxy hint: while running in Direct mode, surface the
+            // local listen port with a one-tap copy so users wiring this up
+            // as an upstream don't have to dig through config. Direct is the
+            // only mode that makes sense here — apps_script and full try to
+            // relay everything via Apps Script, which breaks binary protocols
+            // like Psiphon's. See docs/use-as-upstream.md.
+            //
+            // Gating on PROXY_ONLY: Android allows only one active VPN at a
+            // time. If mhrv-rs is running its own VpnService (VPN_TUN mode),
+            // Psiphon cannot establish its own VPN and the upstream address
+            // here is not actionable. Show the warning copy first so the
+            // user knows to stop, flip to PROXY_ONLY, and Connect again
+            // before pasting the address into Psiphon.
+            //
+            // Vertical Column instead of horizontal Row: in Persian and at
+            // larger font sizes the label + monospace address + copy button
+            // would cramp into a single line. Stacking lets each part wrap
+            // naturally and keeps the copy button reachable.
+            if (isVpnRunning && cfg.mode == Mode.DIRECT) {
+                Spacer(Modifier.height(8.dp))
+                val clipboard = LocalClipboardManager.current
+                val ctx = LocalContext.current
+                val upstreamPort = cfg.listenPort
+                val upstream = "127.0.0.1:$upstreamPort"
+                val copiedMsg = stringResource(R.string.snack_upstream_copied, upstream)
+                val proxyOnly = cfg.connectionMode == ConnectionMode.PROXY_ONLY
+                Column(
+                    modifier = Modifier.fillMaxWidth(),
+                    verticalArrangement = Arrangement.spacedBy(4.dp),
+                ) {
+                    if (!proxyOnly) {
+                        Text(
+                            stringResource(R.string.direct_upstream_vpn_tun_warning),
+                            style = MaterialTheme.typography.labelSmall,
+                            color = ErrRed,
+                        )
+                    }
+                    Text(
+                        stringResource(R.string.direct_upstream_label),
+                        style = MaterialTheme.typography.labelSmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                    Row(
+                        modifier = Modifier.fillMaxWidth(),
+                        verticalAlignment = Alignment.CenterVertically,
+                    ) {
+                        SelectionContainer(modifier = Modifier.weight(1f)) {
+                            Text(
+                                upstream,
+                                style = MaterialTheme.typography.bodyMedium.copy(
+                                    fontFamily = FontFamily.Monospace,
+                                ),
+                                color = if (proxyOnly) OkGreen else MaterialTheme.colorScheme.onSurfaceVariant,
+                            )
+                        }
+                        TextButton(
+                            onClick = {
+                                clipboard.setText(AnnotatedString(upstream))
+                                Toast.makeText(ctx, copiedMsg, Toast.LENGTH_SHORT).show()
+                            },
+                            contentPadding = PaddingValues(horizontal = 8.dp, vertical = 0.dp),
+                        ) {
+                            Text(
+                                stringResource(R.string.btn_copy_lower),
+                                style = MaterialTheme.typography.labelMedium,
+                            )
+                        }
+                    }
+                }
+            }
+
             Spacer(Modifier.height(4.dp))
 
             val appsScriptEnabled = cfg.mode == Mode.APPS_SCRIPT || cfg.mode == Mode.FULL
@@ -901,6 +972,13 @@ private fun ModeDropdown(
             style = MaterialTheme.typography.labelSmall,
             color = MaterialTheme.colorScheme.onSurfaceVariant,
         )
+        if (mode == Mode.DIRECT) {
+            Text(
+                stringResource(R.string.direct_upstream_help),
+                style = MaterialTheme.typography.labelSmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+        }
     }
 }
 

android/app/src/main/res/values-fa/strings.xml

@@ -95,6 +95,13 @@
     <string name="btn_view_quota_on_google">مشاهدهٔ سهمیه در گوگل ←</string>
     <string name="usage_today_note">تخمینی — این همان چیزی است که از این دستگاه رد شده. عدد دقیق در داشبورد گوگل قابل مشاهده است.</string>
 
+    <!-- Direct mode upstream-proxy banner (see docs/use-as-upstream.fa.md). -->
+    <string name="direct_upstream_help">به‌عنوان پروکسی upstream برای سایفون / xray هم کار می‌کند — هاست‌های fronted نشده به‌صورت TCP خام عبور می‌کنند.</string>
+    <string name="direct_upstream_label">آدرس upstream برای سایفون / xray:</string>
+    <string name="direct_upstream_vpn_tun_warning">سایفون به تنها اسلات VPN اندروید نیاز دارد. mhrv-rs را متوقف کن، Connection mode را به PROXY_ONLY تغییر بده، بعد دوباره Connect را بزن — تنها در این حالت سایفون می‌تواند از آدرس زیر استفاده کند.</string>
+    <string name="btn_copy_lower">کپی</string>
+    <string name="snack_upstream_copied">%1$s کپی شد</string>
+
     <!-- "How to use" guide body. Localized — EN copy lives in values. -->
     <string name="help_how_to_use">۱. یک یا چند آدرس deployment از Apps Script (یا فقط ID خام) و همراه آن auth_key خود را جای‌گذاری کنید.\n۲. روی «نصب گواهی MITM» بزنید و پیام تأیید را قبول کنید — گواهی در Downloads/mhrv-ca.crt ذخیره می‌شود و برنامهٔ Settings باز می‌شود. داخل Settings از نوار جست‌وجو «CA certificate» را پیدا کنید و روی همان نتیجه بزنید (نه «VPN &amp; app user certificate» و نه «Wi-Fi»)، سپس mhrv-ca.crt را از Downloads انتخاب کنید. اگر قفل صفحه ندارید، اندروید می‌خواهد یکی تنظیم کنید (الزام سیستم).\n۳. قبل از Start، بخش «مجموعهٔ SNI + تستر» را باز کنید و «تست همه» را بزنید. اگر همه تایم‌اوت شدند یعنی google_ip در دسترس نیست — آن را با یک IP جایگزین کنید که روی شبکهٔ سالم resolve می‌شود (مثلاً `nslookup www.google.com` روی هر دستگاه سالم).\n۴. Start را بزنید و درخواست VPN را تأیید کنید. پل TUN کامل، تمام برنامه‌های دستگاه را خودکار از پروکسی رد می‌کند — نیاز به تنظیم per-app نیست.\n۵. اگر Chrome پیام «504 Relay timeout» نشان داد: deployment شما پاسخ نمی‌دهد. اسکریپت را دوباره deploy کنید، URL جدید /exec را بگیرید و بالا جای‌گذاری کنید. در «لاگ زنده» ببینید خطا از نوع «Relay timeout» است یا «connect:» — نوع خطا مشخص می‌کند کدام لایه مقصر است.\n\nمحدودیت شناخته‌شده — Cloudflare Turnstile («Verify you are human») روی اکثر سایت‌های پشت Cloudflare به‌طور بی‌پایان loop می‌زند. هر درخواست Apps Script از یک IP خروجی چرخشی دیتاسنتر گوگل + یک User-Agent ثابت «Google-Apps-Script» + اثرانگشت TLS گوگل عبور می‌کند. کوکی cf_clearance به tuple (IP, UA, JA3) مربوط به زمان حل چالش گره خورده است، پس درخواست بعدی — از یک IP خروجی متفاوت — دوباره چالش می‌خورد. این مسئله در این برنامه قابل‌حل نیست؛ ذات رلهٔ Apps Script است. سایت‌هایی که فقط بارگذاری اولیه را gate می‌کنند (نه هر درخواست) بعد از یک بار حل، کار خواهند کرد.</string>
 </resources>

android/app/src/main/res/values/strings.xml

@@ -113,6 +113,13 @@
     <string name="btn_view_quota_on_google">View quota on Google →</string>
     <string name="usage_today_note">Estimate — this is what this device relayed. Google\'s dashboard has the authoritative number.</string>
 
+    <!-- Direct mode upstream-proxy banner (see docs/use-as-upstream.md). -->
+    <string name="direct_upstream_help">Also works as an upstream proxy for Psiphon / xray — unfronted hosts pass through as raw TCP.</string>
+    <string name="direct_upstream_label">Upstream for Psiphon / xray:</string>
+    <string name="direct_upstream_vpn_tun_warning">Psiphon needs Android\'s single VPN slot. Stop mhrv-rs, switch Connection mode to PROXY_ONLY, then Connect again — only then can Psiphon use the address below.</string>
+    <string name="btn_copy_lower">copy</string>
+    <string name="snack_upstream_copied">Copied %1$s</string>
+
     <!-- "How to use" guide body. Localized — FA copy lives in values-fa. -->
     <string name="help_how_to_use">1. Paste one or more Apps Script deployment URLs (or bare IDs) and your auth_key.\n2. Tap Install MITM certificate. Confirm the dialog — the cert is saved to Downloads/mhrv-ca.crt and the Settings app opens. Use Settings\' search bar to find \"CA certificate\", tap that result (NOT \"VPN &amp; app user certificate\" or \"Wi-Fi\"), and pick mhrv-ca.crt from Downloads. You\'ll be asked to set a screen lock if you don\'t have one (Android requirement).\n3. Before tapping Start, expand \"SNI pool + tester\" and hit \"Test all\". If every entry times out, your google_ip is unreachable — replace it with one that resolves locally (e.g. `nslookup www.google.com` on any working device).\n4. Tap Start. Accept the VPN prompt. The full TUN bridge routes every app on the device through the proxy — no per-app setup needed.\n5. If Chrome shows \"504 Relay timeout\": your Apps Script deployment isn\'t responding. Redeploy the script, grab the new /exec URL, and paste it above. Watch Live logs for \"Relay timeout\" vs \"connect:\" errors to tell which layer is failing.\n\nKnown limitation — Cloudflare Turnstile (\"Verify you are human\") will loop endlessly on most CF-protected sites. Every Apps Script request uses a rotating Google-datacenter egress IP + a fixed \"Google-Apps-Script\" User-Agent + a Google TLS fingerprint. The cf_clearance cookie is bound to the (IP, UA, JA3) tuple the challenge was solved against, so the NEXT request — from a different egress IP — gets re-challenged. Nothing in this app can fix that; it\'s inherent to Apps Script as a relay. Sites that only gate the initial page load (not every request) will work after one solve.</string>
 </resources>

docs/use-as-upstream.fa.md

@@ -0,0 +1,95 @@
+<div dir="rtl">
+
+# استفاده از mhrv-rs به‌عنوان پروکسی upstream (سایفون، xray، مرورگرها)
+
+نسخهٔ انگلیسی: [docs/use-as-upstream.md](use-as-upstream.md).
+
+به‌طور پیش‌فرض، mhrv-rs یک پروکسی HTTP محلی روی `127.0.0.1:8085` و یک پروکسی SOCKS5 روی `127.0.0.1:8086` در دسترس قرار می‌دهد (پیش‌فرض اندروید: HTTP `8080` و SOCKS5 `1081`). هر ابزاری که تنظیم upstream proxy داشته باشد می‌تواند از این پروکسی عبور کند.
+
+حالت رایج: سرورهای bootstrap سایفون مسدودند، پس upstream proxy سایفون را روی mhrv-rs می‌گذاری تا اولین hop سایفون از طریق تونل SNI-fronting ما به شبکه‌اش برسد.
+
+## از حالت `direct` استفاده کن
+
+حالت‌های `apps_script` و `full` تلاش می‌کنند هر هاست را از رلهٔ Apps Script عبور دهند، که با پروتکل باینری سایفون سازگار نیست. حالت `direct` رله را کنار می‌گذارد: SNI-rewrite برای هاست‌هایی که mhrv-rs می‌شناسد، TCP خام برای بقیه. این دقیقاً همان چیزی است که سایفون نیاز دارد — رمزنگاری end-to-end خودش دست‌نخورده می‌ماند و cert pinning نمی‌شکند.
+
+در رابط دسکتاپ / برنامهٔ اندروید گزینهٔ **Direct (no relay)** را انتخاب کن، یا در کانفیگ بگذار:
+
+<div dir="ltr">
+
+```jsonc
+{
+  "mode": "direct",
+  "listen_host": "127.0.0.1",
+  "listen_port": 8085,
+  "socks5_port": 8086
+}
+```
+
+</div>
+
+## سایفون — ویندوز / مک / لینوکس
+
+۱. برنامهٔ mhrv-rs را در حالت `direct` اجرا کن. host:port زیر دکمهٔ Start نمایش داده می‌شود — روی **copy** بزن.
+
+۲. در سایفون این مسیر را باز کن: **Options** → **Proxy settings** → **Upstream proxy**.
+
+۳. تیک **Connect through an upstream proxy** را بزن.
+
+۴. در فیلد **Hostname** مقدار `127.0.0.1`، در **Port** مقدار `8085` و در **Type** گزینهٔ `HTTP` را انتخاب کن. (یا SOCKS5 روی پورت `8086`.)
+
+۵. روی **Save** بزن، بعد در سایفون **Connect** را بزن.
+
+## سایفون — اندروید
+
+اندروید همزمان فقط یک VPN فعال اجازه می‌دهد و سایفون به این اسلات نیاز دارد. قبل از شروع: برنامهٔ mhrv-rs را باز کن و در بخش Network مقدار **Connection mode** را روی **PROXY_ONLY** بگذار. در این حالت mhrv-rs فقط پروکسی محلی را اجرا می‌کند و اسلات VPN را برای سایفون آزاد می‌گذارد.
+
+۱. در mhrv-rs ابتدا Connection mode را روی `PROXY_ONLY` بگذار، سپس حالت `Direct` را انتخاب کن و **Connect** را بزن. host:port زیر دکمهٔ Connect نمایش داده می‌شود — روی **copy** بزن.
+
+۲. در برنامهٔ سایفون این مسیر را باز کن: **Options** → **Proxy** → **Upstream proxy**.
+
+۳. در فیلد **Host** مقدار `127.0.0.1` و در **Port** مقدار `8080` (برای HTTP) یا `1081` (برای SOCKS5) را وارد کن.
+
+۴. در سایفون **Connect** را بزن.
+
+## تنظیم xray / v2ray
+
+یک outbound از نوع `http` (یا `socks`) اضافه کن که به mhrv-rs اشاره کند:
+
+<div dir="ltr">
+
+```jsonc
+{
+  "outbounds": [
+    {
+      "tag": "proxy",
+      "protocol": "http",
+      "settings": {
+        "servers": [
+          { "address": "127.0.0.1", "port": 8085 }
+        ]
+      }
+    }
+  ]
+}
+```
+
+</div>
+
+## مرورگرها / SwitchyOmega
+
+پروکسی را روی `127.0.0.1:8085` تنظیم کن. چیز دیگری لازم نیست.
+
+## رفع اشکال
+
+- **سایفون روی «در حال اتصال…» می‌ماند** — مطمئن شو mhrv-rs در حالت `direct` است و پورت با چیزی که در سایفون وارد کردی یکی است. در پنل log اخیر رابط mhrv-rs هر CONNECT را که می‌بیند نمایش می‌دهد؛ باید هاست‌های سایفون را آنجا با برچسب `raw-tcp (direct mode: no relay)` ببینی.
+
+- **یک هاست خاص MITM می‌شود در حالی که نمی‌خواهی** — آن را به `passthrough_hosts` در `config.json` اضافه کن. این لیست بر همهٔ تصمیم‌های دیگر dispatch اولویت دارد.
+
+- **برعکس زنجیر کن (outbound از mhrv-rs از طریق سایفون یا xray)** — در `config.json` فیلد `upstream_socks5` را روی پورت SOCKS5 محلی آن ابزار تنظیم کن. flowهای raw-TCP / passthrough از آنجا خارج می‌شوند. ترافیک رلهٔ Apps Script طبق طراحی همچنان از edge گوگل می‌گذرد.
+
+## همچنین ببین
+
+- راهنمای [fronting-groups.md](fronting-groups.md) — افزودن CDNهای غیرگوگلی (Vercel، Fastly، Netlify) به مسیر SNI-rewrite.
+- مرجع کامل [حالت direct در راهنمای کامل](guide.fa.md#حالت-direct).
+
+</div>