feat(appgate): apps with their own login can skip the node login

Some apps carry a complete account system and are broken by an upstream
challenge: git clients speak basic-auth (not browser cookies), and a
BTCPay checkout link handed to a customer must open for that customer.
Both were behind the gate's login page — the "non-browser clients need an
access token" gap disclosed in five consecutive releases.

- New manifest port policy `auth: open`: the daemon still fronts the port
  exactly like `gated` (loopback pin, external binds, frame-header fixes,
  app-down retry page, Tor upstream) but serves it without the login
  challenge. Requires auth_rationale, same burden of proof as `none`.
  Gitea 3001 and BTCPay 23000 declare it.
- Runtime operator override per app (security.set-app-gate → app-configs/
  <id>.json "gateEnabled"), surfaced as Settings → app → Access control.
  Wins over the manifest in both directions and applies on the next
  request — no restart, and it works today on catalog-covered apps whose
  signed manifest still says `gated`.
- The gate resolves policy per-request from the live port map, so a
  toggle takes effect without waiting for the 60s rebind sweep. "Off"
  never releases the port: gated apps are loopback-pinned, so releasing
  would strand them, not open them.
- security.app-gate-status now reports gate_enabled + any override.
- New guard test pins the `auth: open` set (both entries reviewed); the
  `auth: none` count moves 25 → 26, absorbing pre-existing drift from the
  phoenixd onboarding (loopback JSON API with its own generated password).
- Docs: the manifest spec's ports row documented only host/container/
  protocol — bind, auth, auth_rationale and session_passthrough were
  undocumented. Added a full "Ports & the app gate" section plus a
  developer-guide entry telling app authors to enforce their own auth
  regardless, since the operator can flip the gate either way.

Verified live on archi-dev-box from an external address: gated → 401 gate
page; override off → Gitea 200 own page, BTCPay 302 to its own login,
git-over-HTTP info/refs 200; override on → 401 again; clear → default.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

core/archipelago/src/api/rpc/appgate.rs

@@ -42,6 +42,13 @@ impl RpcHandler {
                     "port": g.port,
                     "app_id": g.app_id,
                     "app_name": g.app_name,
+                    // Is the login challenge active on this port right now
+                    // (manifest default + operator override, resolved)?
+                    "gate_enabled": g.auth_enabled,
+                    // Whether an operator override is recorded, and what the
+                    // manifest would do without it — the UI needs all three
+                    // to render a meaningful toggle.
+                    "override": crate::container::app_gate_config::gate_override(&g.app_id),
                 })
             })
             .collect();
@@ -56,4 +63,59 @@ impl RpcHandler {
             "exempt": exempt,
         }))
     }
+
+    /// `security.set-app-gate` — the operator's per-app gate toggle.
+    ///
+    /// Params: `{ id: "<app_id>", enabled: true | false | null }`.
+    /// `enabled: null` clears the override so the manifest default applies
+    /// again. Takes effect on the next request (the gate resolves per-request
+    /// policy from the live port map) — no rebind, no restart.
+    pub(in crate::api::rpc) async fn handle_set_app_gate(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let app_id = params
+            .get("id")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing id"))?
+            .to_string();
+        let enabled = match params.get("enabled") {
+            None | Some(serde_json::Value::Null) => None,
+            Some(serde_json::Value::Bool(b)) => Some(*b),
+            Some(other) => anyhow::bail!("enabled must be true, false or null, got {other}"),
+        };
+
+        // Only apps the gate actually fronts have a challenge to toggle.
+        // Writing an override for anything else would sit silently in the
+        // config doing nothing — reject instead so a typo'd id is loud.
+        let port_map = self.app_gate.port_map().await;
+        if !port_map.gated_ports().any(|g| g.app_id == app_id) {
+            anyhow::bail!(
+                "'{app_id}' has no gate-fronted ports — nothing to toggle \
+                 (auth: none/local ports are manifest-declared, not runtime-toggled)"
+            );
+        }
+
+        crate::container::app_gate_config::write_gate_override(&app_id, enabled)
+            .map_err(|e| anyhow::anyhow!("Failed to persist gate override: {e}"))?;
+        // Rebuild the port map now so the change is live on the next request
+        // instead of after the next 60s sweep.
+        self.app_gate.refresh().await;
+
+        let effective: Vec<serde_json::Value> = self
+            .app_gate
+            .port_map()
+            .await
+            .gated_ports()
+            .filter(|g| g.app_id == app_id)
+            .map(|g| serde_json::json!({ "port": g.port, "gate_enabled": g.auth_enabled }))
+            .collect();
+        tracing::info!(
+            app = %app_id,
+            override_ = ?enabled,
+            "app gate override updated by operator"
+        );
+        Ok(serde_json::json!({ "id": app_id, "override": enabled, "ports": effective }))
+    }
 }

core/archipelago/src/api/rpc/dispatcher.rs

@@ -489,6 +489,7 @@ impl RpcHandler {
 
             // System monitoring
             "security.app-gate-status" => self.handle_app_gate_status().await,
+            "security.set-app-gate" => self.handle_set_app_gate(params).await,
             "system.get-hostname" => self.handle_system_get_hostname().await,
             "system.stats" => self.handle_system_stats().await,
             "system.processes" => self.handle_system_processes().await,

core/archipelago/src/appgate/identity.rs

@@ -40,6 +40,15 @@ pub struct GatedPort {
     /// companion UIs proxy that cookie to the daemon's authenticated
     /// endpoints; for every other app the gate strips its own credential.
     pub session_passthrough: bool,
+    /// Does the gate challenge for the dashboard login on this port?
+    ///
+    /// Default comes from the manifest (`auth: gated`/undeclared → true,
+    /// `auth: open` → false); the operator's runtime override
+    /// (`app_gate_config`, Settings → app → App gate) wins over both.
+    /// False does NOT release the port — the gate keeps binding and
+    /// proxying (frame-header fixes, app-down page, Tor upstream); it just
+    /// forwards every request to the app's own authentication.
+    pub auth_enabled: bool,
 }
 
 /// A port deliberately left unauthenticated, and the manifest's stated reason.
@@ -187,6 +196,18 @@ pub fn build_port_map() -> PortMap {
         }
     }
 
+    // The operator's runtime override wins over the manifest default, in
+    // both directions: un-gate an app that fronts its own login, or force
+    // the challenge back onto an `auth: open` port. Overrides only toggle
+    // the challenge on gate-fronted ports — they never bind or release
+    // anything, so a stale override cannot expose or strand a port.
+    let overrides = crate::container::app_gate_config::all_gate_overrides();
+    for gp in map.gated.values_mut() {
+        if let Some(enabled) = overrides.get(&gp.app_id) {
+            gp.auth_enabled = *enabled;
+        }
+    }
+
     map.exempt.sort_by_key(|e| e.port);
     map
 }
@@ -229,7 +250,10 @@ fn classify_manifest(manifest: &AppManifest, map: &mut PortMap) {
             // Explicit opt-in: the app is on loopback and the daemon
             // owns the external addresses. This is the ONLY way a
             // port gets bound by the gate, regardless of `bind`.
-            PortAuth::Gated => {
+            // `open` is the same takeover with the login challenge
+            // defaulted off — the app fronts its own authentication
+            // (rationale-required, see PortAuth::Open).
+            PortAuth::Gated | PortAuth::Open => {
                 map.gated.insert(
                     port.host,
                     GatedPort {
@@ -239,6 +263,7 @@ fn classify_manifest(manifest: &AppManifest, map: &mut PortMap) {
                         icon: icon.clone(),
                         declared: true,
                         session_passthrough: port.session_passthrough,
+                        auth_enabled: port.auth_policy() == PortAuth::Gated,
                     },
                 );
             }
@@ -289,6 +314,10 @@ fn classify_manifest(manifest: &AppManifest, map: &mut PortMap) {
                         // An undeclared port never gets the node session —
                         // passthrough is an explicit manifest opt-in only.
                         session_passthrough: false,
+                        // Undeclared ports are challenged wherever the gate
+                        // can stand: reporting-and-protecting is the safe
+                        // default (operator override still applies below).
+                        auth_enabled: true,
                     },
                 );
             }

core/archipelago/src/appgate/mod.rs

@@ -139,6 +139,14 @@ impl AppGate {
         app: &GatedPort,
         client_ip: IpAddr,
     ) -> Response<Body> {
+        // The accept loop captured its GatedPort at bind time; per-request
+        // policy (the operator's gate on/off toggle, session_passthrough)
+        // must come from the live map or a Settings change would only apply
+        // to ports (re)bound after the next sweep. Falls back to the bound
+        // snapshot when the port momentarily leaves the map mid-refresh.
+        let live = self.port_map.read().await.gated(app.port).cloned();
+        let app = live.as_ref().unwrap_or(app);
+
         let path = req.uri().path().to_string();
 
         if let Some(action) = path.strip_prefix(GATE_PREFIX) {
@@ -169,6 +177,17 @@ impl AppGate {
             return proxy_to_app(req, app, true).await;
         }
 
+        // Gate challenge disabled for this app (manifest `auth: open`, or
+        // the operator's Settings toggle): forward everything to the app's
+        // own authentication. The Authorization header passes through
+        // untouched — git clients speak basic-auth to Gitea, API clients
+        // carry the app's own tokens. Gate cookies are still stripped in
+        // proxy_to_app (an ungated app must never see the node session),
+        // and the frame fixes / app-down page still apply.
+        if !app.auth_enabled {
+            return proxy_to_app(req, app, false).await;
+        }
+
         match self.authorize(req.headers(), &app.app_id).await {
             // The credential was a cookie (or none was needed): the
             // Authorization header, if any, belongs to the app. Forward it.
@@ -1164,6 +1183,7 @@ mod tests {
             icon: None,
             declared: true,
             session_passthrough: false,
+            auth_enabled: true,
         }
     }
 

core/archipelago/src/container/app_gate_config.rs

@@ -0,0 +1,136 @@
+//! Per-app operator override for the app gate's login requirement.
+//!
+//! The manifest declares each port's *default* policy (`auth: gated` = the
+//! gate challenges, the new `auth: open` = the gate fronts the port but does
+//! not challenge). This store holds the operator's runtime override — set
+//! from Settings → app details — so a node owner can un-gate an app that
+//! carries its own login (Gitea, BTCPay) or force the gate back onto an
+//! `open` app, without editing manifests or waiting for a catalog re-sign.
+//!
+//! Lives in the same merge-preserving per-app JSON files as the version
+//! preferences (`/var/lib/archipelago/app-configs/<app_id>.json`, key
+//! `"gateEnabled"`). Absent key = follow the manifest default.
+
+use std::collections::HashMap;
+use std::path::PathBuf;
+
+use serde_json::{Map, Value};
+
+fn config_dir() -> PathBuf {
+    let base = std::env::var("ARCHIPELAGO_DATA_DIR")
+        .unwrap_or_else(|_| "/var/lib/archipelago".to_string());
+    PathBuf::from(base).join("app-configs")
+}
+
+fn config_path(app_id: &str) -> PathBuf {
+    config_dir().join(format!("{app_id}.json"))
+}
+
+fn read_raw(app_id: &str) -> Map<String, Value> {
+    match std::fs::read_to_string(config_path(app_id)) {
+        Ok(s) => serde_json::from_str::<Value>(&s)
+            .ok()
+            .and_then(|v| v.as_object().cloned())
+            .unwrap_or_default(),
+        Err(_) => Map::new(),
+    }
+}
+
+/// The operator's gate override for one app. `None` = no override recorded —
+/// the manifest default applies.
+pub fn gate_override(app_id: &str) -> Option<bool> {
+    read_raw(app_id).get("gateEnabled").and_then(Value::as_bool)
+}
+
+/// Every recorded override, keyed by app id (the config file stem). Used by
+/// the gate's port-map build so one directory scan covers all apps.
+pub fn all_gate_overrides() -> HashMap<String, bool> {
+    let mut out = HashMap::new();
+    let Ok(entries) = std::fs::read_dir(config_dir()) else {
+        return out;
+    };
+    for entry in entries.flatten() {
+        let path = entry.path();
+        if path.extension().and_then(|e| e.to_str()) != Some("json") {
+            continue;
+        }
+        let Some(app_id) = path.file_stem().and_then(|s| s.to_str()) else {
+            continue;
+        };
+        if let Some(v) = gate_override(app_id) {
+            out.insert(app_id.to_string(), v);
+        }
+    }
+    out
+}
+
+/// Set (`Some`) or clear (`None`) the override, preserving every other key in
+/// the app's config file. Temp+rename so a crash mid-write can't truncate.
+pub fn write_gate_override(app_id: &str, enabled: Option<bool>) -> std::io::Result<()> {
+    let path = config_path(app_id);
+    let mut obj = read_raw(app_id);
+    match enabled {
+        Some(v) => {
+            obj.insert("gateEnabled".to_string(), Value::Bool(v));
+        }
+        None => {
+            obj.remove("gateEnabled");
+        }
+    }
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent)?;
+    }
+    let serialized = serde_json::to_string_pretty(&Value::Object(obj))
+        .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?;
+    let tmp = path.with_extension("json.tmp");
+    std::fs::write(&tmp, serialized.as_bytes())?;
+    std::fs::rename(&tmp, &path)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn with_tmp_data_dir<T>(f: impl FnOnce() -> T) -> T {
+        let dir = tempfile::tempdir().expect("tempdir");
+        // Serialize env mutation across tests in this module.
+        static LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
+        let _guard = LOCK.lock().unwrap_or_else(|e| e.into_inner());
+        std::env::set_var("ARCHIPELAGO_DATA_DIR", dir.path());
+        let out = f();
+        std::env::remove_var("ARCHIPELAGO_DATA_DIR");
+        out
+    }
+
+    #[test]
+    fn absent_file_means_no_override() {
+        with_tmp_data_dir(|| {
+            assert_eq!(gate_override("gitea"), None);
+            assert!(all_gate_overrides().is_empty());
+        });
+    }
+
+    #[test]
+    fn write_read_clear_roundtrip_preserves_other_keys() {
+        with_tmp_data_dir(|| {
+            // Seed an existing config with an unrelated key.
+            std::fs::create_dir_all(config_dir()).unwrap();
+            std::fs::write(config_path("gitea"), r#"{"autoUpdate": true}"#).unwrap();
+
+            write_gate_override("gitea", Some(false)).unwrap();
+            assert_eq!(gate_override("gitea"), Some(false));
+            assert_eq!(all_gate_overrides().get("gitea"), Some(&false));
+
+            // The unrelated key survives.
+            let raw = std::fs::read_to_string(config_path("gitea")).unwrap();
+            let v: Value = serde_json::from_str(&raw).unwrap();
+            assert_eq!(v.get("autoUpdate"), Some(&Value::Bool(true)));
+
+            write_gate_override("gitea", None).unwrap();
+            assert_eq!(gate_override("gitea"), None);
+            let raw = std::fs::read_to_string(config_path("gitea")).unwrap();
+            let v: Value = serde_json::from_str(&raw).unwrap();
+            assert_eq!(v.get("autoUpdate"), Some(&Value::Bool(true)));
+        });
+    }
+}

core/archipelago/src/container/mod.rs

@@ -1,4 +1,5 @@
 pub mod app_catalog;
+pub mod app_gate_config;
 pub mod bitcoin_ui;
 pub mod boot_reconciler;
 pub mod companion;