fbi-proxy 1.12.0 → 1.14.0

package/README.md

@@ -11,42 +11,50 @@ FBI-Proxy provides easy HTTPS access to your local services with intelligent dom
 
 ### Current Features ✅
 
-- **Intelligent Domain Routing**: Multiple routing patterns for flexible service access
+- **One-command HTTPS gateway**: `bunx fbi-proxy --with-caddy --with-auth --provider snolab --domain fbi.com` brings up Caddy (auto-downloaded), fbi-auth (Firebase-backed Google sign-in), and the Rust proxy together — zero config needed on `.fbi.com`.
+- **Rule-based Domain Routing** via `routes.yaml`:
   - Port-based routing (e.g., `3000.fbi.com` → `localhost:3000`)
   - Host--Port routing (e.g., `api--3001.fbi.com` → `api:3001`)
   - Subdomain routing with Host headers (e.g., `admin.app.fbi.com` → `app:80`)
   - Direct host forwarding (e.g., `myserver.fbi.com` → `myserver:80`)
-- **WebSocket Support**: Full WebSocket connection support for all routing patterns
-- **High Performance**: Built with Rust for optimal performance and low resource usage
-- **Easy Setup**: Simple one-command installation and startup
-- **Docker Support**: Available as a Docker image for containerized deployments
-- **Flexible Configuration**: Environment variables and CLI options for customization
-- **Cross-Platform**: Works on macOS, Linux, and Windows
-- **Integration Ready**: Compatible with reverse proxies like Caddy for HTTPS
+  - Placeholder syntax (`{name}`, `{name:int}`, `{name:slug}`, `{name:multi}`) for custom rules — see [docs/routing.md](docs/routing.md)
+- **HTTPS Upstreams**: Targets with an `https://` prefix connect to upstream over TLS (Mozilla webpki roots).
+- **WebSocket Support**: Full WebSocket forwarding (`ws://` and `wss://`) for all routing patterns.
+- **Auth Gateway**: Google OAuth / Firebase Auth / zero-config snolab default IdP — JWT cookie scoped to `Domain=.your-domain` for cross-subdomain SSO. Audit log at `~/.config/fbi-proxy/audit.log`.
+- **High Performance**: Built with Rust for optimal performance and low resource usage.
+- **Easy Setup**: Simple one-command installation and startup.
+- **Docker Support**: Available as a Docker image for containerized deployments.
+- **Flexible Configuration**: Environment variables, CLI options, and `routes.yaml` overrides.
+- **Cross-Platform**: Pre-built binaries for macOS, Linux, and Windows (x64 + arm64).
+- **Integration Ready**: Compatible with reverse proxies like Caddy for HTTPS (and bundles its own `--with-caddy` automation).
 
 ## Roadmap
 
 ### Shipped ✅
 
-- [x] **Auto Caddy Setup** - One-command bootstrap that generates a Caddyfile for the chosen domain and supervises Caddy alongside fbi-proxy and fbi-auth (`bunx fbi-proxy --with-caddy --with-auth --domain example.dev`). Caddy binary is auto-downloaded from GitHub Releases on first run (SHA-512 verified against the release's `checksums.txt`), cached at `~/.fbi-proxy/bin/caddy`. Set `FBI_CADDY_AUTO_DOWNLOAD=false` to opt out. See [docs/auth/setup.md](lib/fbi-auth/docs/setup.md#automatic-setup-with---with-caddy-phase-3--shipped).
+- [x] **Auto Caddy Setup** — One-command bootstrap that generates a Caddyfile for the chosen domain and supervises Caddy alongside fbi-proxy and fbi-auth (`bunx fbi-proxy --with-caddy --with-auth --domain example.dev`). Caddy binary is auto-downloaded from GitHub Releases on first run (SHA-512 verified against the release's `checksums.txt`), cached at `~/.fbi-proxy/bin/caddy`. Set `FBI_CADDY_AUTO_DOWNLOAD=false` to opt out.
+- [x] **Auth Gateway** — Google OAuth, Firebase Auth, and a **zero-config snolab default IdP** (Firebase-based, live on `fbi.com`). Cookie-based SSO across `*.your-domain`. Sliding-window refresh, configurable threshold, JSONL audit log at `~/.config/fbi-proxy/audit.log`. See [lib/fbi-auth/docs/setup.md](lib/fbi-auth/docs/setup.md) and [lib/fbi-auth/docs/snolab.md](lib/fbi-auth/docs/snolab.md).
+- [x] **Rule-based Routing** — `routes.yaml` with placeholder syntax (`{name}`, `{name:int}`, `{name:slug}`, `{name:multi}`). DNS-passthrough, k8s, Docker, and PR-preview recipes in [docs/routing.md](docs/routing.md). Override the bundled defaults with `--routes` or `FBI_PROXY_ROUTES`.
+- [x] **HTTPS Upstream Support** — Route target with an `https://` prefix triggers TLS to upstream via `hyper-rustls` + Mozilla webpki roots. Backward compatible — plain `host:port` still uses HTTP. WebSocket upgrades flip to `wss://` automatically.
+- [x] **Cross-platform Releases** — Every push builds six platforms in parallel (linux x64/arm64, macOS x64/arm64, windows x64/arm64). See [docs/cross-compile-tradeoffs.html](docs/cross-compile-tradeoffs.html).
 
 ### Next Up 🚧
 
-- [ ] **Custom Domain Wizard** - Interactive setup that prints the DNS records to add (`*.example.dev → <ip>`) and generates the matching Caddyfile / DNS-01 TLS block
-- [ ] **Built-in HTTPS (optional)** - Native TLS termination via rustls + ACME so Caddy becomes optional for simple setups
-- [ ] **Configuration File Support** - YAML/JSON config for persistent routing rules
-- [ ] **Access Control** - Domain filtering, host/port whitelisting
-- [ ] **Request Logging** - Basic access logs for debugging
-- [ ] **Health Checks** - Simple upstream service availability monitoring
+- [x] **Custom Domain Wizard polish** — Print the DNS A-records to add (`*.example.dev → <ip>`) and a Caddyfile-with-DNS-01 sample for Cloudflare during `--reconfigure` on a non-fbi.com domain
+- [x] **Hot Reload** — `routes.yaml` is watched; edits reload atomically without a restart (typos keep the previous rules live)
+- [ ] **Metrics** — `/varz`-style counters: requests, 2xx/4xx/5xx, upstream-connect-failures, sessions-issued, sessions-refreshed (Prometheus format)
+- [ ] **Health Checks** — Active upstream liveness probes, not just per-request failure detection
+- [ ] **Cloudflare Tunnel / ngrok Integration** — Expose `*.your-domain` publicly without owning a static IP
 
 ### Future Improvements 🔮
 
-- [ ] **Load Balancing** - Round-robin between multiple upstream targets
-- [ ] **Metrics** - Basic statistics (requests, response times, errors)
-- [ ] **Hot Reload** - Update configuration without restart
-- [ ] **Custom Headers** - Add/modify headers for specific routes
-- [ ] **Cloudflare Tunnel / ngrok Integration** - Expose `*.your-domain` to the public internet without owning a static IP
-- [ ] **Auth Gateway** - Built-in basic auth / OIDC so public exposure is safe by default
+- [ ] **Load Balancing** — Round-robin between multiple upstream targets for one route
+- [ ] **Custom Headers per route** — Beyond `Host:`, add response headers or rewrite request headers
+
+### Won't do
+
+- ~~**Built-in HTTPS via rustls + ACME**~~ — Caddy already does this very well, and the `--with-caddy` UX is one extra flag. Adding another ACME client to the Rust binary is more code, more attack surface, and another implementation of a solved problem. Caddy stays the canonical TLS path.
+- ~~**SQLite session storage**~~ — JWT + `sessionSecret` rotation covers the threat model for fbi-proxy's intended scale (solo / small-team self-hosted). See [revoking sessions](lib/fbi-auth/docs/setup.md#revoking-sessions).
 
 ## Routing Examples
 

package/dist/cli.js

@@ -5529,8 +5529,40 @@ async function runWizard(prompter, opts) {
   prompter.print("Config preview:");
   prompter.print(JSON.stringify(redact(cfg), null, 2));
   prompter.print("");
+  if (cleanDomain !== "fbi.com") {
+    printCustomDomainHints(prompter, cleanDomain);
+  }
   return cfg;
 }
+function printCustomDomainHints(prompter, domain) {
+  prompter.print("─── Custom-domain DNS + TLS hints ───");
+  prompter.print("");
+  prompter.print(`Your domain is '${domain}' (not the default fbi.com).`);
+  prompter.print(`You'll need DNS A-records pointing the wildcard + sso host`);
+  prompter.print(`at the public IP of the machine running fbi-proxy:`);
+  prompter.print("");
+  prompter.print(`    *.${domain}     A    <your-public-ip>`);
+  prompter.print(`    sso.${domain}   A    <your-public-ip>      (covered by the wildcard,`);
+  prompter.print(`                                                 but call it out explicitly)`);
+  prompter.print("");
+  prompter.print(`For wildcard TLS via Let's Encrypt you need DNS-01 (HTTP-01`);
+  prompter.print(`can't issue wildcards). With Cloudflare DNS:`);
+  prompter.print("");
+  prompter.print(`  1. Create a Cloudflare API token with Zone:DNS:Edit on '${domain}'.`);
+  prompter.print(`  2. Export it: CLOUDFLARE_API_TOKEN=...`);
+  prompter.print(`  3. Run with --with-caddy --tls-mode auto. fbi-proxy will generate`);
+  prompter.print(`     a Caddyfile that uses Caddy's cloudflare DNS plugin:`);
+  prompter.print("");
+  prompter.print(`     *.${domain} {`);
+  prompter.print(`       tls { dns cloudflare {env.CLOUDFLARE_API_TOKEN} }`);
+  prompter.print(`       reverse_proxy 127.0.0.1:{$FBI_PROXY_PORT}`);
+  prompter.print(`     }`);
+  prompter.print("");
+  prompter.print(`If you're just testing locally without public DNS, point your`);
+  prompter.print(`/etc/hosts at 127.0.0.1 and pass --tls-mode internal — Caddy will`);
+  prompter.print(`use its local CA (the cert won't be trusted by other machines).`);
+  prompter.print("");
+}
 function redact(c) {
   return {
     ...c,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fbi-proxy",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "FBI-Proxy provides easy HTTPS access to your local services with intelligent domain routing",
   "keywords": [
     "development-tools",

package/rs/fbi-proxy.rs

@@ -11,7 +11,8 @@ use hyper_tungstenite::{HyperWebsocket, WebSocketStream};
 use hyper_util::client::legacy::{Client, connect::HttpConnector};
 use hyper_util::rt::TokioIo;
 use hyper_rustls::HttpsConnector;
-use log::{error, info};
+use arc_swap::ArcSwap;
+use log::{error, info, warn};
 use regex::Regex;
 use std::convert::Infallible;
 use std::net::SocketAddr;
@@ -33,7 +34,10 @@ pub struct FBIProxy {
     client: Client<HttpsConnector<HttpConnector>, BoxBody>,
     number_regex: Regex,
     domain_filter: Option<String>,
-    compiled_routes: Vec<CompiledRoute>,
+    /// Compiled routes wrapped in an ArcSwap so they can be replaced
+    /// atomically at runtime (hot reload from `--routes`). Reads use
+    /// `.load()` and never block; writes are atomic Arc swaps.
+    compiled_routes: Arc<ArcSwap<Vec<CompiledRoute>>>,
 }
 
 /*
@@ -85,10 +89,17 @@ impl FBIProxy {
             client,
             number_regex: Regex::new(r"^\d+$").unwrap(),
             domain_filter,
-            compiled_routes,
+            compiled_routes: Arc::new(ArcSwap::from_pointee(compiled_routes)),
         }
     }
 
+    /// Return a handle to the live routes Arc so callers (e.g. the
+    /// file watcher) can swap them at runtime without re-creating the
+    /// proxy.
+    pub fn routes_handle(&self) -> Arc<ArcSwap<Vec<CompiledRoute>>> {
+        Arc::clone(&self.compiled_routes)
+    }
+
     fn landing_page_html() -> String {
         r#"<!DOCTYPE html>
 <html lang="en">
@@ -216,8 +227,12 @@ npx fbi-proxy -d fbi.example.com  # Only accept *.fbi.example.com</pre>
             }
         }
 
+        // Lock-free read of the live routes (may have been swapped by
+        // the file watcher mid-flight). `.load()` returns an Arc; we
+        // hold a reference for the duration of the match.
+        let routes_guard = self.compiled_routes.load();
         let hit = routes::match_host_with_domain(
-            &self.compiled_routes,
+            routes_guard.as_ref(),
             host_header,
             self.domain_filter.as_deref(),
         )?;
@@ -616,16 +631,115 @@ fn load_routes(yaml_src: &str, source_label: &str) -> Vec<CompiledRoute> {
     }
 }
 
+/// Parse + compile a routes file without panicking. Returns Err with a
+/// human-readable message on any failure. Used by the hot-reload path
+/// where we want to log + keep current rules rather than crash.
+fn try_reload_routes(path: &str) -> Result<Vec<CompiledRoute>, String> {
+    let yaml = std::fs::read_to_string(path)
+        .map_err(|e| format!("read {}: {}", path, e))?;
+    let parsed = routes::parse_yaml(&yaml)
+        .map_err(|e| format!("parse {}: {}", path, e))?;
+    routes::compile(parsed.routes)
+        .map_err(|e| format!("compile {}: {}", path, e))
+}
+
+/// Watch a routes file and atomically swap in new rules on change.
+/// Debounces flurries of FS events (some editors save by truncate+
+/// rewrite which can fire multiple notifications in ~ms). On parse or
+/// compile failure, log a warning and leave the existing rules in
+/// place — the running proxy continues to work with whatever last
+/// loaded successfully.
+fn spawn_routes_watcher(
+    path: String,
+    handle: Arc<ArcSwap<Vec<CompiledRoute>>>,
+) {
+    use notify::{RecursiveMode, Watcher};
+    use std::sync::mpsc;
+
+    std::thread::spawn(move || {
+        let (tx, rx) = mpsc::channel();
+        let mut watcher = match notify::recommended_watcher(move |res| {
+            // Best-effort forward; if the receiver is gone the watcher
+            // thread is shutting down anyway.
+            let _ = tx.send(res);
+        }) {
+            Ok(w) => w,
+            Err(e) => {
+                error!("[routes hot-reload] failed to create watcher: {}", e);
+                return;
+            }
+        };
+
+        if let Err(e) = watcher.watch(
+            std::path::Path::new(&path),
+            RecursiveMode::NonRecursive,
+        ) {
+            error!("[routes hot-reload] failed to watch {}: {}", path, e);
+            return;
+        }
+
+        info!("[routes hot-reload] watching {}", path);
+
+        // Debounce window — wait this long for the burst to subside
+        // before reloading.
+        const DEBOUNCE: Duration = Duration::from_millis(150);
+
+        loop {
+            // Block for the next event.
+            match rx.recv() {
+                Ok(Ok(_event)) => {}
+                Ok(Err(e)) => {
+                    warn!("[routes hot-reload] watcher error: {}", e);
+                    continue;
+                }
+                Err(_) => break, // sender dropped — proxy shutting down
+            }
+            // Drain any additional events that arrive during the debounce
+            // window, so a single save that fires 3 events triggers
+            // exactly one reload.
+            loop {
+                match rx.recv_timeout(DEBOUNCE) {
+                    Ok(_) => continue,
+                    Err(_) => break,
+                }
+            }
+
+            match try_reload_routes(&path) {
+                Ok(new_routes) => {
+                    let n = new_routes.len();
+                    handle.store(Arc::new(new_routes));
+                    info!("[routes hot-reload] reloaded {} rule(s) from {}", n, path);
+                }
+                Err(reason) => {
+                    warn!(
+                        "[routes hot-reload] reload failed, keeping previous rules: {}",
+                        reason
+                    );
+                }
+            }
+        }
+    });
+}
+
 pub async fn start_proxy_server(
     host: Option<&str>,
     port: u16,
     domain_filter: Option<String>,
     compiled_routes: Vec<CompiledRoute>,
+    watch_path: Option<String>,
 ) -> Result<(), BoxError> {
     let host = host.unwrap_or("127.0.0.1");
     let addr: SocketAddr = format!("{}:{}", host, port).parse()?;
     let proxy = Arc::new(FBIProxy::new(domain_filter.clone(), compiled_routes));
 
+    // Hot-reload: when the user pointed us at a routes file with
+    // --routes, spawn a background watcher that re-parses + swaps in
+    // new rules on file change. Failures leave the current rules in
+    // place — never crash the running proxy because of a typo in YAML.
+    if let Some(path) = watch_path {
+        spawn_routes_watcher(path, proxy.routes_handle());
+    }
+
     let listener = TcpListener::bind(addr).await?;
 
     info!("FBI Proxy server running on http://{}", addr);
@@ -783,8 +897,10 @@ TRY RUN:
     };
 
     // Load routes: either from --routes <path> or the bundled default.
-    let compiled_routes = if routes_path.is_empty() {
-        load_routes(BUNDLED_ROUTES_YAML, "bundled routes.yaml")
+    // The bundled YAML is baked into the binary and can't change at
+    // runtime, so hot reload only applies to the --routes path.
+    let (compiled_routes, watch_path) = if routes_path.is_empty() {
+        (load_routes(BUNDLED_ROUTES_YAML, "bundled routes.yaml"), None)
     } else {
         let src = match std::fs::read_to_string(routes_path) {
             Ok(s) => s,
@@ -793,7 +909,10 @@ TRY RUN:
                 std::process::exit(2);
             }
         };
-        load_routes(&src, &format!("routes file '{}'", routes_path))
+        (
+            load_routes(&src, &format!("routes file '{}'", routes_path)),
+            Some(routes_path.clone()),
+        )
     };
 
     let rt = tokio::runtime::Runtime::new().unwrap();
@@ -802,7 +921,15 @@ TRY RUN:
             "Starting FBI-Proxy on {}:{} with domain filter: {:?}",
             host, port, domain_filter
         );
-        if let Err(e) = start_proxy_server(Some(host), port, domain_filter, compiled_routes).await {
+        if let Err(e) = start_proxy_server(
+            Some(host),
+            port,
+            domain_filter,
+            compiled_routes,
+            watch_path,
+        )
+        .await
+        {
             error!("Failed to start proxy server: {}", e);
         }
     });

package/ts/auth/setupWizard.ts

@@ -133,9 +133,57 @@ export async function runWizard(
   prompter.print(JSON.stringify(redact(cfg), null, 2));
   prompter.print("");
 
+  if (cleanDomain !== "fbi.com") {
+    printCustomDomainHints(prompter, cleanDomain);
+  }
+
   return cfg;
 }
 
+function printCustomDomainHints(prompter: WizardPrompter, domain: string) {
+  prompter.print("─── Custom-domain DNS + TLS hints ───");
+  prompter.print("");
+  prompter.print(`Your domain is '${domain}' (not the default fbi.com).`);
+  prompter.print(`You'll need DNS A-records pointing the wildcard + sso host`);
+  prompter.print(`at the public IP of the machine running fbi-proxy:`);
+  prompter.print("");
+  prompter.print(`    *.${domain}     A    <your-public-ip>`);
+  prompter.print(
+    `    sso.${domain}   A    <your-public-ip>      (covered by the wildcard,`,
+  );
+  prompter.print(
+    `                                                 but call it out explicitly)`,
+  );
+  prompter.print("");
+  prompter.print(`For wildcard TLS via Let's Encrypt you need DNS-01 (HTTP-01`);
+  prompter.print(`can't issue wildcards). With Cloudflare DNS:`);
+  prompter.print("");
+  prompter.print(
+    `  1. Create a Cloudflare API token with Zone:DNS:Edit on '${domain}'.`,
+  );
+  prompter.print(`  2. Export it: CLOUDFLARE_API_TOKEN=...`);
+  prompter.print(
+    `  3. Run with --with-caddy --tls-mode auto. fbi-proxy will generate`,
+  );
+  prompter.print(`     a Caddyfile that uses Caddy's cloudflare DNS plugin:`);
+  prompter.print("");
+  prompter.print(`     *.${domain} {`);
+  prompter.print(`       tls { dns cloudflare {env.CLOUDFLARE_API_TOKEN} }`);
+  prompter.print(`       reverse_proxy 127.0.0.1:{$FBI_PROXY_PORT}`);
+  prompter.print(`     }`);
+  prompter.print("");
+  prompter.print(
+    `If you're just testing locally without public DNS, point your`,
+  );
+  prompter.print(
+    `/etc/hosts at 127.0.0.1 and pass --tls-mode internal — Caddy will`,
+  );
+  prompter.print(
+    `use its local CA (the cert won't be trusted by other machines).`,
+  );
+  prompter.print("");
+}
+
 function redact(c: AuthConfigShape): AuthConfigShape {
   return {
     ...c,