Update docs and add contribution hygiene notes

.gitignore

@@ -23,6 +23,7 @@ env/
 # IDE
 .vscode/
 .idea/
+*.code-workspace
 *.swp
 *.swo
 *~

PULL_REQUEST_DRAFT.md

@@ -0,0 +1,67 @@
+# PR Draft
+
+## Summary
+
+This PR improves `apps_script` mode compatibility and local usability.
+
+Changes included:
+
+- add built-in SOCKS5 listener alongside the HTTP proxy
+- use sticky per-host Apps Script routing instead of naive per-request round-robin
+- preserve redirect semantics for `307/308` while still normalizing `301/302/303`
+- avoid batching/coalescing/cache shortcuts for stateful requests
+- make caching safer by skipping requests/responses involving cookies, auth, private cache directives, and `Set-Cookie`
+- improve Linux CA trust detection
+- make Google direct-tunnel routing more conservative
+- add adaptive fallback from failed direct Google tunnels back to the MITM relay path
+- preserve browser capability headers in `Code.gs` (`sec-ch-ua*`, `sec-fetch-*`)
+- preserve multi-value response headers from Apps Script via `getAllHeaders()`
+- keep signed URLs safer via `escaping: false` in Apps Script fetch options
+
+## Motivation
+
+The previous behavior worked for some simple/static sites, but modern sites and Google web apps were sensitive to:
+
+- request-to-request route churn
+- incorrect redirect method handling
+- over-aggressive batching/cache reuse
+- over-broad Google direct-tunnel shortcuts
+- lost response headers such as `Set-Cookie`
+- stripped browser capability headers in the Apps Script relay
+
+This PR does not claim full compatibility for all websites. It focuses on making the existing architecture more stable and more predictable.
+
+## Testing
+
+Local verification:
+
+- `python3 -m py_compile main.py proxy_server.py domain_fronter.py mitm.py h2_transport.py ws.py cert_installer.py`
+
+Observed behavior during manual testing:
+
+- improved: YouTube, Facebook, Gmail, Drive
+- improved / partial: Gemini loads further than before
+- still limited by architecture: ChatGPT / Cloudflare PAT flows, Google Meet browser-gating / unsupported-browser flow in `apps_script` mode
+
+## Important limitation
+
+`apps_script` mode still uses Google Apps Script `UrlFetch`, which is not a real browser transport.
+
+That means some sites may still reject or degrade requests because of:
+
+- TLS / transport fingerprint differences
+- anti-bot / PAT / Turnstile / attestation checks
+- browser capability detection
+- WebRTC / media / browser-runtime assumptions
+
+## Deployment note
+
+If `Code.gs` changes are included, users must create a new Google Apps Script deployment and update `script_id` in `config.json`.
+
+## Security / hygiene checklist
+
+- no real `config.json` included
+- no real deployment IDs included
+- `AUTH_KEY` reset to placeholder
+- no local logs included
+- no local workspace files intended for commit

README.md

@@ -89,6 +89,8 @@ This is the "relay" that sits on Google's servers and fetches websites for you.
      "auth_key": "your-secret-password-here",
      "listen_host": "127.0.0.1",
      "listen_port": 8085,
+     "socks5_enabled": true,
+     "socks5_port": 1080,
      "log_level": "INFO",
      "verify_ssl": true
    }
@@ -99,10 +101,10 @@ This is the "relay" that sits on Google's servers and fetches websites for you.
 ### Step 4: Run
 
 ```bash
-python main.py
+python3 main.py
 ```
 
-You should see a message saying the proxy is running on `127.0.0.1:8085`.
+You should see a message saying the HTTP proxy is running on `127.0.0.1:8085` and SOCKS5 on `127.0.0.1:1080`.
 
 ### Step 5: Set Up Your Browser
 
@@ -111,6 +113,7 @@ Set your browser to use the proxy:
 - **Proxy Address:** `127.0.0.1`
 - **Proxy Port:** `8085`
 - **Type:** HTTP
+- **Optional SOCKS5 Port:** `1080`
 
 **How to set proxy in common browsers:**
 - **Firefox:** Settings → General → Network Settings → Manual proxy → enter `127.0.0.1` port `8085` for HTTP Proxy → check "Also use this proxy for HTTPS"
@@ -220,12 +223,14 @@ If you change `Code.gs`, you must **create a new deployment** in Google Apps Scr
 ## Command Line Options
 
 ```bash
-python main.py                          # Normal start
+python3 main.py                          # Normal start
-python main.py -p 9090                  # Use port 9090 instead
+python3 main.py -p 9090                  # Use HTTP port 9090 instead
-python main.py --log-level DEBUG        # Show detailed logs
+python3 main.py --socks5-port 1081       # Use SOCKS5 port 1081
-python main.py -c /path/to/config.json  # Use a different config file
+python3 main.py --disable-socks5         # Disable SOCKS5 listener
-python main.py --install-cert           # Install MITM CA certificate and exit
+python3 main.py --log-level DEBUG        # Show detailed logs
-python main.py --no-cert-check          # Skip automatic CA install check on startup
+python3 main.py -c /path/to/config.json  # Use a different config file
+python3 main.py --install-cert           # Install MITM CA certificate and exit
+python3 main.py --no-cert-check          # Skip automatic CA install check on startup
 ```
 
 > **Auto-install:** On startup (MITM mode), the proxy automatically checks if the CA certificate is trusted and attempts to install it. Use `--no-cert-check` to skip this. If auto-install fails (e.g. needs elevation), run `python main.py --install-cert` manually or follow Step 6 above.

README_FA.md

@@ -86,6 +86,8 @@ cp config.example.json config.json
   "auth_key": "your-secret-password-here",
   "listen_host": "127.0.0.1",
   "listen_port": 8085,
+  "socks5_enabled": true,
+  "socks5_port": 1080,
   "log_level": "INFO",
   "verify_ssl": true
 }
@@ -97,10 +99,10 @@ cp config.example.json config.json
 ### مرحله 4: اجرا
 
 ```bash
-python main.py
+python3 main.py
 ```
 
-اگر همه‌چیز درست باشد، پراکسی روی `127.0.0.1:8085` بالا می‌آید.
+اگر همه‌چیز درست باشد، پراکسی HTTP روی `127.0.0.1:8085` و SOCKS5 روی `127.0.0.1:1080` بالا می‌آید.
 
 ### مرحله 5: تنظیم مرورگر
 
@@ -109,6 +111,7 @@ python main.py
 - **Proxy Address:** `127.0.0.1`
 - **Proxy Port:** `8085`
 - **Type:** HTTP
+- **SOCKS5 Port (اختیاری):** `1080`
 
 نمونه تنظیم مرورگرها:
 
@@ -208,12 +211,14 @@ Firefox معمولا certificate store جداگانه دارد:
 ## دستورهای اجرا
 
 ```bash
-python main.py
+python3 main.py
-python main.py -p 9090
+python3 main.py -p 9090
-python main.py --log-level DEBUG
+python3 main.py --socks5-port 1081
-python main.py -c /path/to/config.json
+python3 main.py --disable-socks5
-python main.py --install-cert        # نصب گواهی CA و خروج
+python3 main.py --log-level DEBUG
-python main.py --no-cert-check       # رد شدن از بررسی خودکار گواهی
+python3 main.py -c /path/to/config.json
+python3 main.py --install-cert        # نصب گواهی CA و خروج
+python3 main.py --no-cert-check       # رد شدن از بررسی خودکار گواهی
 ```
 
 > **نصب خودکار:** هنگام اجرا در حالت `apps_script`، برنامه به‌طور خودکار بررسی می‌کند که آیا گواهی CA قابل اعتماد است یا نه و در صورت نیاز آن را نصب می‌کند. اگر نصب خودکار ناموفق بود (مثلاً نیاز به دسترسی مدیر دارد)، می‌توانید دستور `python main.py --install-cert` را اجرا کنید یا مراحل مرحله ۶ را دنبال کنید.