feat(proxy): short-circuit configured blocked hosts locally

Add a config-backed block_hosts list for destinations that should be answered by the local proxy before any relay, tunnel, SNI rewrite, or upstream SOCKS5 dispatch is attempted. The matcher intentionally reuses the existing passthrough host semantics: exact entries match only that hostname, while leading-dot entries match the bare suffix and its subdomains with case-insensitive trailing-dot normalization.

HTTP proxy requests now check the parsed target host at ingress. Blocked plain HTTP requests and blocked CONNECT authorities receive a local 204 No Content response with Connection: close and Content-Length: 0, so the browser gets a deterministic terminal response without opening an outbound socket or consuming Apps Script quota.

SOCKS5 CONNECT requests now check the resolved request target before the success reply is sent. Blocked targets receive a ruleset-failure response and no outbound connection is opened. SOCKS5 UDP ASSOCIATE datagrams also check each parsed datagram target and drop blocked destinations before creating or reusing a tunnel-mux UDP session.

The shared tunnel dispatcher keeps a defensive block_hosts guard as well, so future ingress paths cannot accidentally bypass the local policy and reach raw TCP passthrough, Full Tunnel, Apps Script relay, or SNI rewrite. This keeps the policy local to the client and avoids any changes to Code.gs, CodeFull.gs, or tunnel-node.

Wire block_hosts through the flat Config, the TOML [network] section, JSON-to-TOML migration serialization, and the desktop UI form state. The UI does not expose an editor for the list yet, but it now preserves hand-edited TOML entries on Save instead of dropping them.

Document the TOML shape in the guide, add block_hosts to the checked-in TOML examples, and cover both TOML round-trip/migration behavior and host matching semantics with focused unit tests.

Author: maybeknott

config.direct.example.toml

@@ -8,6 +8,7 @@ listen_host = "127.0.0.1"
 listen_port = 8085
 socks5_port = 8086
 verify_ssl = true
+block_hosts = []
 
 [network.hosts]
 

config.example.toml

@@ -10,6 +10,7 @@ listen_host = "127.0.0.1"
 listen_port = 8085
 socks5_port = 8086
 verify_ssl = true
+block_hosts = []
 
 [network.hosts]
 

config.exit-node.example.toml

@@ -13,6 +13,7 @@ listen_host = "0.0.0.0"
 listen_port = 8085
 socks5_port = 8086
 verify_ssl = true
+block_hosts = []
 
 [network.hosts]
 
@@ -44,4 +45,4 @@ hosts = [
   "openai.com",
   "aistudio.google.com",
   "ai.google.dev",
-]
+]

config.full.example.toml

@@ -10,6 +10,7 @@ listen_host = "127.0.0.1"
 listen_port = 8085
 socks5_port = 8086
 verify_ssl = true
+block_hosts = []
 
 [network.hosts]
 

docs/guide.fa.md

@@ -206,6 +206,17 @@ upstream_socks5 = "127.0.0.1:50529"
 
 HTTP / HTTPS مثل قبل از Apps Script می‌رود (تغییری نمی‌کند)، تونل بازنویسی SNI برای `google.com` / `youtube.com` همچنان از هر دو دور می‌زند — یوتیوب به سرعت قبل می‌ماند و تلگرام هم تونل واقعی پیدا می‌کند.
 
+## مسدودسازی محلی host
+
+برای مقصدهایی که نباید سهمیهٔ Apps Script، ظرفیت tunnel-node، یا ترافیک SOCKS5 upstream مصرف کنند، از `block_hosts` استفاده کن. entryهای دقیق فقط همان hostname را match می‌کنند؛ entryهایی که با `.` شروع می‌شوند هم parent suffix و هم subdomainها را match می‌کنند.
+
+```toml
+[network]
+block_hosts = ["ads.example.com", ".tracker.example"]
+```
+
+درخواست‌های HTTP و HTTP CONNECT مسدودشده پاسخ محلی `204 No Content` می‌گیرند. درخواست‌های SOCKS5 CONNECT قبل از باز شدن هر اتصال خروجی، reply خطای ruleset می‌گیرند.
+
 ## حالت تونل کامل
 
 `"mode": "full"` **تمام** ترافیک را end-to-end از Apps Script و یک [tunnel-node](../tunnel-node/) راه دور رد می‌کند — بدون نیاز به نصب گواهی MITM. TCP به‌صورت سشن‌های پایدار تونل، و UDP از کلاینت‌های اندروید / TUN از طریق SOCKS5 `UDP ASSOCIATE` به tunnel-node که UDP واقعی را از سمت سرور منتشر می‌کند. مبادله: تأخیر بیشتر هر درخواست (هر بایت Apps Script → tunnel-node → مقصد می‌رود)، اما برای هر پروتکل و هر برنامه‌ای بدون نصب CA کار می‌کند.
@@ -360,6 +371,7 @@ sni_hosts = ["www.google.com", "drive.google.com", "docs.google.com"]
 | ماسک Script ID | به‌صورت `prefix…suffix` در لاگ، تا Deployment ID افشا نشود |
 | UI دسکتاپ | egui — کراس‌پلتفرم، بدون bundler |
 | چِین SOCKS5 upstream | اختیاری برای ترافیک غیر-HTTP (MTProto تلگرام، IMAP، SSH …) |
+| مسدودسازی محلی `block_hosts` | short-circuit قبل از relay، tunnel، بازنویسی SNI، یا SOCKS5 upstream |
 | Pre-warm pool | اولین درخواست TLS handshake به لبهٔ گوگل را skip می‌کند |
 | چرخش SNI per-connection | بین `{www, mail, drive, docs, calendar}.google.com` |
 | Parallel relay | اختیاری: fan-out به N اسکریپت همزمان، اولین موفقیت برمی‌گردد |

docs/guide.md

@@ -206,6 +206,17 @@ upstream_socks5 = "127.0.0.1:50529"
 
 HTTP / HTTPS keeps going through Apps Script (no change), and the SNI-rewrite tunnel for `google.com` / `youtube.com` keeps bypassing both — YouTube stays as fast as before while Telegram gets a real tunnel.
 
+## Local host blocking
+
+Use `block_hosts` for destinations that should be answered locally instead of spending Apps Script quota, tunnel-node capacity, or upstream SOCKS5 traffic. Exact entries match only that hostname; entries that start with `.` match the parent suffix and its subdomains.
+
+```toml
+[network]
+block_hosts = ["ads.example.com", ".tracker.example"]
+```
+
+Blocked HTTP and HTTP CONNECT requests receive a local `204 No Content` response. SOCKS5 CONNECT requests receive a ruleset failure reply before any outbound connection is opened.
+
 ## Full Tunnel mode
 
 `"mode": "full"` routes **all** traffic end-to-end through Apps Script and a remote [tunnel-node](../tunnel-node/) — no MITM certificate needed. TCP carried as persistent tunnel sessions, UDP from Android / TUN clients via SOCKS5 `UDP ASSOCIATE` to the tunnel-node which emits real UDP server-side. Trade-off: higher per-request latency (every byte goes Apps Script → tunnel-node → destination), but works for any protocol and any app, no CA install required.
@@ -356,6 +367,7 @@ This port focuses on the **`apps_script` mode** — the only one that reliably w
 - [x] Script IDs masked in logs (`prefix…suffix`) so logs don't leak deployment IDs
 - [x] Desktop UI (egui) — cross-platform, no bundler needed
 - [x] Optional upstream SOCKS5 chaining for non-HTTP traffic (Telegram MTProto, IMAP, SSH…)
+- [x] Local `block_hosts` short-circuit before relay, tunnel, SNI rewrite, or upstream SOCKS5 dispatch
 - [x] Connection pool pre-warm on startup
 - [x] Per-connection SNI rotation across `{www, mail, drive, docs, calendar}.google.com`
 - [x] Optional parallel script-ID dispatch (`parallel_relay`): fan-out to N script instances, return first success

src/bin/ui.rs

@@ -252,6 +252,9 @@ struct FormState {
     normalize_x_graphql: bool,
     youtube_via_relay: bool,
     passthrough_hosts: Vec<String>,
+    /// Config-only local block list. Round-tripped from config.toml so
+    /// UI Save preserves hand-edited quota-saving filters.
+    block_hosts: Vec<String>,
     /// Round-tripped from config.toml so the UI's save path doesn't
     /// drop the user's setting. Not currently exposed as a UI control;
     /// users edit `block_quic` directly in `config.toml` (Issue #213).
@@ -379,6 +382,7 @@ fn load_form() -> (FormState, Option<String>) {
             normalize_x_graphql: c.normalize_x_graphql,
             youtube_via_relay: c.youtube_via_relay,
             passthrough_hosts: c.passthrough_hosts.clone(),
+            block_hosts: c.block_hosts.clone(),
             block_quic: c.block_quic,
             block_stun: c.block_stun,
             disable_padding: c.disable_padding,
@@ -419,6 +423,7 @@ fn load_form() -> (FormState, Option<String>) {
             normalize_x_graphql: false,
             youtube_via_relay: false,
             passthrough_hosts: Vec::new(),
+            block_hosts: Vec::new(),
             block_quic: true,
             block_stun: false,
             disable_padding: false,
@@ -578,6 +583,8 @@ impl FormState {
             // Similarly config-only for now; round-trips through the
             // file so the UI doesn't drop the user's entries on save.
             passthrough_hosts: self.passthrough_hosts.clone(),
+            // Local block list: config-only, preserved on Save.
+            block_hosts: self.block_hosts.clone(),
             // Issue #213: block_quic is config-only for now (no UI
             // control yet). Round-trip through the file so save
             // doesn't drop a user-set true.

src/config.rs

@@ -180,6 +180,17 @@ pub struct Config {
     #[serde(default)]
     pub passthrough_hosts: Vec<String>,
 
+    /// Local block list evaluated before any relay, SNI rewrite, upstream
+    /// SOCKS5, or Full Tunnel dispatch. Matching follows the same convention
+    /// as `passthrough_hosts`: exact hostnames match only themselves, and
+    /// leading-dot entries match the bare suffix plus subdomains.
+    ///
+    /// This is intentionally local-only. It saves Apps Script quota and
+    /// tunnel latency for hosts the user does not want to contact at all,
+    /// without changing the remote Apps Script or tunnel-node data planes.
+    #[serde(default)]
+    pub block_hosts: Vec<String>,
+
     /// Block outbound QUIC (UDP/443) at the SOCKS5 listener.
     ///
     /// QUIC is HTTP/3-over-UDP. In `apps_script` mode it's hopeless —
@@ -793,6 +804,8 @@ pub struct TomlNetwork {
     pub sni_hosts: Option<Vec<String>>,
     #[serde(default)]
     pub passthrough_hosts: Vec<String>,
+    #[serde(default)]
+    pub block_hosts: Vec<String>,
     #[serde(default = "default_tunnel_doh")]
     pub tunnel_doh: bool,
     #[serde(default = "default_block_doh")]
@@ -817,6 +830,7 @@ impl Default for TomlNetwork {
             block_stun: default_block_stun(),
             sni_hosts: None,
             passthrough_hosts: Vec::new(),
+            block_hosts: Vec::new(),
             tunnel_doh: default_tunnel_doh(),
             block_doh: default_block_doh(),
             bypass_doh_hosts: Vec::new(),
@@ -907,6 +921,7 @@ impl From<TomlConfig> for Config {
             normalize_x_graphql: t.relay.normalize_x_graphql,
             youtube_via_relay: t.relay.youtube_via_relay,
             passthrough_hosts: t.network.passthrough_hosts,
+            block_hosts: t.network.block_hosts,
             block_stun: t.network.block_stun,
             block_quic: t.network.block_quic,
             disable_padding: t.relay.disable_padding,
@@ -959,6 +974,7 @@ impl From<&Config> for TomlConfig {
                 block_stun: c.block_stun,
                 sni_hosts: c.sni_hosts.clone(),
                 passthrough_hosts: c.passthrough_hosts.clone(),
+                block_hosts: c.block_hosts.clone(),
                 tunnel_doh: c.tunnel_doh,
                 block_doh: c.block_doh,
                 bypass_doh_hosts: c.bypass_doh_hosts.clone(),
@@ -1388,6 +1404,29 @@ mode = "direct"
         assert_eq!(cfg.hosts.get("test.example.com"), Some(&"5.6.7.8".to_string()));
     }
 
+    #[test]
+    fn toml_parses_block_hosts_and_roundtrips_through_config() {
+        let s = r#"
+[relay]
+mode = "direct"
+
+[network]
+block_hosts = ["ads.example.com", ".tracker.example"]
+"#;
+        let toml_cfg: TomlConfig = toml::from_str(s).unwrap();
+        let cfg = Config::from(toml_cfg);
+        assert_eq!(
+            cfg.block_hosts,
+            vec!["ads.example.com".to_string(), ".tracker.example".to_string()]
+        );
+
+        let toml_again = TomlConfig::from(&cfg);
+        assert_eq!(
+            toml_again.network.block_hosts,
+            vec!["ads.example.com".to_string(), ".tracker.example".to_string()]
+        );
+    }
+
     #[test]
     fn toml_multi_script_id_array() {
         let s = r#"
@@ -1423,7 +1462,8 @@ script_id = "ABCDEF"
   "mode": "apps_script",
   "auth_key": "MY_SECRET_KEY_123",
   "script_id": "ABCDEF",
-  "listen_port": 8085
+  "listen_port": 8085,
+  "block_hosts": ["ads.example.com", ".tracker.example"]
 }"#;
         let dir = std::env::temp_dir();
         let json_path = dir.join("mhrv-migration-test.json");
@@ -1446,8 +1486,13 @@ script_id = "ABCDEF"
         assert_eq!(cfg.auth_key, cfg2.auth_key);
         assert_eq!(cfg.script_ids_resolved(), cfg2.script_ids_resolved());
         assert_eq!(cfg.listen_port, cfg2.listen_port);
+        assert_eq!(cfg.block_hosts, cfg2.block_hosts);
+        assert_eq!(
+            cfg2.block_hosts,
+            vec!["ads.example.com".to_string(), ".tracker.example".to_string()]
+        );
 
         let _ = std::fs::remove_file(&json_path);
         let _ = std::fs::remove_file(&toml_path);
     }
-}
+}

src/proxy_server.rs

@@ -237,6 +237,10 @@ pub struct RewriteCtx {
     /// and pass through as plain TCP (optionally via upstream_socks5).
     /// See config.rs `passthrough_hosts` for matching rules. Issues #39, #127.
     pub passthrough_hosts: Vec<String>,
+    /// User-configured hostnames that should be answered locally instead of
+    /// consuming relay, tunnel, SNI-rewrite, or upstream SOCKS5 resources.
+    /// Matching follows `passthrough_hosts` semantics.
+    pub block_hosts: Vec<String>,
     /// If true, drop SOCKS5 UDP datagrams destined for port 443 so
     /// callers fall back to TCP/HTTPS. See config.rs `block_quic` for
     /// the trade-off. Issue #213.
@@ -404,6 +408,10 @@ pub fn matches_passthrough(host: &str, list: &[String]) -> bool {
     })
 }
 
+pub fn matches_block_host(host: &str, list: &[String]) -> bool {
+    matches_passthrough(host, list)
+}
+
 impl ProxyServer {
     pub fn new(config: &Config, mitm: Arc<Mutex<MitmCertManager>>) -> Result<Self, ProxyError> {
         let mode = config
@@ -507,6 +515,7 @@ impl ProxyServer {
             mode,
             youtube_via_relay: config.youtube_via_relay,
             passthrough_hosts: config.passthrough_hosts.clone(),
+            block_hosts: config.block_hosts.clone(),
             block_quic: config.block_quic,
             block_stun: config.block_stun,
             bypass_doh: !config.tunnel_doh,
@@ -810,11 +819,16 @@ async fn handle_http_client(
         }
     };
 
-    let (method, target, _version, _headers) = parse_request_head(&head)
+    let (method, target, _version, headers) = parse_request_head(&head)
         .ok_or_else(|| std::io::Error::new(std::io::ErrorKind::InvalidData, "bad request"))?;
 
     if method.eq_ignore_ascii_case("CONNECT") {
         let (host, port) = parse_host_port(&target);
+        if matches_block_host(&host, &rewrite_ctx.block_hosts) {
+            tracing::info!("CONNECT {}:{} blocked locally by block_hosts", host, port);
+            write_http_no_content(&mut sock).await?;
+            return Ok(());
+        }
         // Mirror the SOCKS5 short-circuit: if the tunnel-node just failed
         // this (host, port) with unreachable, return 502 immediately rather
         // than acknowledging the CONNECT and blowing tunnel quota on a
@@ -834,6 +848,13 @@ async fn handle_http_client(
         sock.flush().await?;
         dispatch_tunnel(sock, host, port, fronter, mitm, rewrite_ctx, tunnel_mux).await
     } else {
+        if let Some((host, port, _path)) = resolve_plain_http_target(&target, &headers) {
+            if matches_block_host(&host, &rewrite_ctx.block_hosts) {
+                tracing::info!("HTTP {}:{} blocked locally by block_hosts", host, port);
+                write_http_no_content(&mut sock).await?;
+                return Ok(());
+            }
+        }
         // Plain HTTP proxy request (e.g. `GET http://…`).
         //
         // apps_script mode: relay through the Apps Script fronter (which
@@ -927,6 +948,14 @@ async fn handle_socks5_client(
         return handle_socks5_udp_associate(sock, rewrite_ctx, tunnel_mux).await;
     }
 
+    if matches_block_host(&host, &rewrite_ctx.block_hosts) {
+        tracing::info!("SOCKS5 CONNECT -> {}:{} blocked locally by block_hosts", host, port);
+        sock.write_all(&[0x05, 0x02, 0x00, 0x01, 0, 0, 0, 0, 0, 0])
+            .await?;
+        sock.flush().await?;
+        return Ok(());
+    }
+
     // Negative-cache short-circuit: if the tunnel-node just failed to reach
     // this exact (host, port) with `Network is unreachable` / `No route to
     // host`, reply 0x04 (Host unreachable) immediately. Saves a 1.5–2s tunnel
@@ -1190,6 +1219,11 @@ async fn handle_socks5_udp_associate(
                 };
                 let payload_slice = &recv_buf[payload_off..n];
 
+                if matches_block_host(&target.host, &rewrite_ctx.block_hosts) {
+                    tracing::debug!("udp dropped: target {} blocked by block_hosts", target.host);
+                    continue;
+                }
+
                 // Issue #213: client-side QUIC block. UDP/443 is
                 // HTTP/3 — drop the datagram silently so the client
                 // stack retries a couple of times and then falls back
@@ -1504,6 +1538,16 @@ async fn write_socks5_reply(
     sock.flush().await
 }
 
+async fn write_http_no_content(sock: &mut TcpStream) -> std::io::Result<()> {
+    sock.write_all(
+        b"HTTP/1.1 204 No Content\r\n\
+          Connection: close\r\n\
+          Content-Length: 0\r\n\r\n",
+    )
+    .await?;
+    sock.flush().await
+}
+
 /// Parse the SOCKS5 UDP frame header and return the target plus the byte
 /// offset at which the payload starts. Splitting "structure parsing"
 /// from "give me a payload slice" lets the recv hot path stay on a
@@ -1627,6 +1671,12 @@ async fn dispatch_tunnel(
     rewrite_ctx: Arc<RewriteCtx>,
     tunnel_mux: Option<Arc<TunnelMux>>,
 ) -> std::io::Result<()> {
+    if matches_block_host(&host, &rewrite_ctx.block_hosts) {
+        tracing::info!("dispatch {}:{} -> blocked locally by block_hosts", host, port);
+        drop(sock);
+        return Ok(());
+    }
+
     // 0. User-configured passthrough list wins over every other path.
     //    If the host matches `passthrough_hosts`, we raw-TCP it (through
     //    upstream_socks5 if set) and never touch Apps Script, SNI-rewrite,
@@ -3501,6 +3551,21 @@ mod tests {
         assert!(matches_passthrough("example.com.", &list));
     }
 
+    #[test]
+    fn block_hosts_use_passthrough_matching_rules() {
+        let list = vec![
+            "ads.example.com".to_string(),
+            ".tracker.example".to_string(),
+            "  ".to_string(),
+        ];
+        assert!(matches_block_host("ads.example.com", &list));
+        assert!(matches_block_host("ADS.EXAMPLE.COM.", &list));
+        assert!(!matches_block_host("cdn.ads.example.com", &list));
+        assert!(matches_block_host("tracker.example", &list));
+        assert!(matches_block_host("pixel.tracker.example", &list));
+        assert!(!matches_block_host("nottracker.example", &list));
+    }
+
     #[test]
     fn doh_default_list_exact_matches() {
         let extra: Vec<String> = vec![];