`37b841d`

close sprint two blockers

Authored by mfwolffe <wolffemf@dukes.jmu.edu> 2 months ago

SHA: 37b841dc7b138df51b29d45d034f2396f6e2caa9
Parents: 617b876
Tree: eb65dc2

8 changed files

Status	File	+	-
M	`README.md`	1	0
M	`examples/config.toml`	4	0
A	`examples/sprint-02-validation-report-2026-02-18.md`	46	0
M	`examples/sprint-02-validation.md`	17	0
M	`examples/validate-sprint-02.sh`	14	10
M	`garcard/src/agent.rs`	110	19
M	`garcard/src/config.rs`	39	0
M	`garcard/src/daemon.rs`	67	0

README.mdmodified

 . `GARCARD_POLKIT_HELPER_SOCKET`
 . `GARCARD_PROMPT_COMMAND`
 . `GARCARD_PROMPT_TIMEOUT_SECS`
 +10. `GARCARD_BACKEND_HEALTHCHECK_SECS`
  See `examples/config.toml` for a starter file.

examples/config.tomlmodified

  # Locale sent to polkit authority registration.
  locale = "en_US.UTF-8"
++
 +# Backend health check interval in seconds.
 +# Failed checks trigger a reconnect attempt for the selected auth backend.
 +backend_healthcheck_secs = "5"

examples/sprint-02-validation-report-2026-02-18.mdadded

 +# Sprint 02 Validation Report (2026-02-18)
++
 +## Environment
 +1. Host: `mizu` (NixOS)
 +2. Daemon run mode: `GARCARD_AGENT_BACKEND=polkit`
 +3. Socket: `/run/user/1000/garcard.sock`
++
 +## Baseline Checks
 +1. `garcardctl ping` -> success.
 +2. `garcardctl status` -> running with `agent_backend: polkit`.
 +3. `garcardctl auth-summary` -> `idle`.
++
 +## Live Policy Checks
 +1. `pkcheck --allow-user-interaction --process $$ --action-id org.freedesktop.login1.power-off`
 +Result:
 +1. Exit code `0`.
 +2. No challenge emitted (policy already authorized in this session context).
++
 +2. `pkcheck --allow-user-interaction --process $$ --action-id com.mesonbuild.install.run`
 +Result:
 +1. Exit code `1` (`Not authorized.`).
 +2. Daemon logs showed live challenge callback:
 +   - `Started active polkit auth request ...`
 +   - `Processing polkit auth request ...`
 +   - `Starting helper authentication dialog ...`
 +3. `garcardctl auth-summary` after call -> `timeout`.
++
 +## Reconnect Validation
 +1. `kill -HUP <garcard-pid>` (forced reconnect path).
 +2. Daemon logs:
 +   - `Received SIGHUP; forcing backend reconnect`
 +   - `Unregistered polkit authentication agent`
 +   - `Registered polkit authentication agent`
 +3. Post-check:
 +   - `garcardctl status` remained responsive.
 +   - `garcardctl auth-summary` remained consistent.
++
 +## Optional Root-Level Disruption Check
 +1. Attempted `systemctl restart polkit`.
 +2. Result: `Access denied` (no root/system permission from this validation context).
 +3. Root-level service restart scenario remains for host-owner execution if desired.
++
 +## Conclusion
 +1. Sprint 02 auth callback path is live and receiving real polkit challenge requests.
 +2. Timeout state is observable and propagated through IPC summary.
 +3. Backend reconnect behavior is validated through forced reconnect workflow.

examples/sprint-02-validation.mdmodified

 . One active request at a time.
 . Additional requests queue and process FIFO.
 . No deadlock after cancel/failure/success.
++
 +## Backend Reconnect (Bus/Authority Disruption)
 +1. Start daemon with visible logs:
 +   - `RUST_LOG=garcard=debug cargo run -p garcard -- daemon`
 +2. In another terminal, capture status:
 +   - `cargo run -q -p garcardctl -- status`
 +3. Force reconnect path without root:
 +   - `kill -HUP <garcard-pid>`
 +4. Wait at least one health interval (default 5s), then check status and logs.
 +5. Optional root-level disruption check:
 +   - `sudo systemctl restart polkit`
++
 +Expected:
 +1. Log shows forced reconnect path (`Received SIGHUP; forcing backend reconnect`).
 +2. Backend re-registers without daemon process restart.
 +3. `garcardctl status` remains responsive during/after reconnect attempt.
 +4. Optional root-level disruption should trigger maintenance reconnect attempts.

examples/validate-sprint-02.shmodified

  ACTION_ID="${1:-org.freedesktop.login1.power-off}"
 -if ! command -v garcardctl >/dev/null 2>&1; then
 -  echo "garcardctl not found in PATH"
 -  echo "Run from this repo with: cargo run -p garcardctl -- <command>"
 -  exit 1
 -fi
+-
  if ! command -v pkcheck >/dev/null 2>&1; then
    echo "pkcheck not found; install polkit tools to run live auth validation"
    exit 1
  fi
 +if command -v garcardctl >/dev/null 2>&1; then
 +  GARCARDCTL=(garcardctl)
 +else
 +  GARCARDCTL=(cargo run -q -p garcardctl --)
 +fi
++
 +run_garcardctl() {
 +  "${GARCARDCTL[@]}" "$@"
 +}
++
  echo "[1/5] Check daemon connectivity"
 -garcardctl ping
 +run_garcardctl ping
  echo "[2/5] Check daemon status"
 -garcardctl status
 +run_garcardctl status
  echo "[3/5] Check pre-auth summary"
 -garcardctl auth-summary
 +run_garcardctl auth-summary
  echo "[4/5] Trigger interactive policy check"
  echo "Action ID: ${ACTION_ID}"
  echo "pkcheck exit code: ${PKCHECK_RC}"
  echo "[5/5] Check post-auth summary"
 -garcardctl auth-summary
 +run_garcardctl auth-summary
  cat <<'EOF'
  Exit code hints:

garcard/src/agent.rsmodified

      fn name(&self) -> &'static str;
      fn register(&mut self) -> Result<()>;
      fn unregister(&mut self) -> Result<()>;
 +    fn maintain(&mut self) -> Result<()> {
 +        Ok(())
 +    }
+ }
  /// Placeholder backend used during Sprint 01 scaffolding.
          )?;
          Ok(proxy)
+     }
++
 +    fn peer_proxy(connection: &Connection) -> Result<Proxy<'_>> {
 +        let proxy = Proxy::new(
 +            connection,
 +            "org.freedesktop.PolicyKit1",
 +            "/org/freedesktop/PolicyKit1/Authority",
 +            "org.freedesktop.DBus.Peer",
 +        )?;
 +        Ok(proxy)
 +    }
++
 +    fn ping_authority(connection: &Connection) -> Result<()> {
 +        let _: () = Self::peer_proxy(connection)?.call("Ping", &())?;
 +        Ok(())
 +    }
+ }
  impl AuthAgentBackend for PolkitAgent {
                  &(
                      &self.subject,
                      self.locale.as_str(),
 -                    self.object_path.clone(),
 +                    self.object_path.to_string(),
                  ),
              )?;
              Ok(())
+         }
          if let Some(connection) = &self.connection {
 -            match Self::proxy(connection)?.call::<_, _, ()>(
 -                "UnregisterAuthenticationAgent",
 -                &(
 -                    &self.subject,
 -                    self.locale.as_str(),
 -                    self.object_path.clone(),
 -                ),
 -            ) {
 -                Ok(()) => {
 -                    tracing::info!(
 -                        backend = self.name(),
 -                        "Unregistered polkit authentication agent"
 -                    );
 -                }
 +            match Self::proxy(connection) {
 +                Ok(proxy) => match proxy.call::<_, _, ()>(
 +                    "UnregisterAuthenticationAgent",
 +                    &(&self.subject, self.object_path.to_string()),
 +                ) {
 +                    Ok(()) => {
 +                        tracing::info!(
 +                            backend = self.name(),
 +                            "Unregistered polkit authentication agent"
 +                        );
 +                    }
 +                    Err(err) => {
 +                        tracing::warn!(
 +                            error = %err,
 +                            "Failed to unregister polkit authentication agent"
 +                        );
 +                    }
 +                },
                  Err(err) => {
 -                    tracing::warn!(error = %err, "Failed to unregister polkit authentication agent");
 +                    tracing::warn!(
 +                        error = %err,
 +                        "Failed to create polkit authority proxy during unregister"
 +                    );
+                 }
+             }
          self.connection = None;
          Ok(())
+     }
++
 +    fn maintain(&mut self) -> Result<()> {
 +        if !self.registered {
 +            return self.register();
 +        }
++
 +        let is_healthy = self
 +            .connection
 +            .as_ref()
 +            .map(|connection| Self::ping_authority(connection).is_ok())
 +            .unwrap_or(false);
 +        if is_healthy {
 +            return Ok(());
 +        }
++
 +        tracing::warn!(
 +            backend = self.name(),
 +            "Polkit backend health check failed; attempting reconnect"
 +        );
 +        let _ = self.unregister();
 +        self.register()
 +    }
+ }
  fn build_subject() -> Subject {
 +    if let Some(session_id) = current_session_id() {
 +        let mut details = HashMap::new();
 +        let value = zbus::zvariant::Value::from(session_id.as_str());
 +        if let Ok(session_value) = OwnedValue::try_from(value) {
 +            details.insert("session-id".to_string(), session_value);
 +            return ("unix-session".to_string(), details);
 +        }
 +    }
++
      let mut details = HashMap::new();
      details.insert("pid".to_string(), OwnedValue::from(std::process::id()));
      details.insert(
          "uid".to_string(),
          OwnedValue::from(nix::unistd::geteuid().as_raw()),
      );
 +    if let Some(start_time) = process_start_time_ticks() {
 +        details.insert("start-time".to_string(), OwnedValue::from(start_time));
 +    } else {
 +        tracing::warn!("Unable to determine process start-time for polkit subject");
 +    }
      ("unix-process".to_string(), details)
+ }
 +fn process_start_time_ticks() -> Option<u64> {
 +    let stat = std::fs::read_to_string("/proc/self/stat").ok()?;
 +    let (_head, tail) = stat.rsplit_once(") ")?;
 +    let mut fields = tail.split_whitespace();
 +    fields.nth(19)?.parse::<u64>().ok()
 +}
++
 +fn current_session_id() -> Option<String> {
 +    if let Ok(raw) = std::env::var("XDG_SESSION_ID") {
 +        let trimmed = raw.trim();
 +        if !trimmed.is_empty() {
 +            return Some(trimmed.to_string());
 +        }
 +    }
++
 +    let raw = std::fs::read_to_string("/proc/self/sessionid").ok()?;
 +    let trimmed = raw.trim();
 +    if trimmed.is_empty() || trimmed == "4294967295" {
 +        return None;
 +    }
++
 +    Some(trimmed.to_string())
 +}
++
  #[cfg(test)]
  mod tests {
      use super::*;
      #[test]
      fn subject_uses_unix_process_kind() {
          let subject = build_subject();
 -        assert_eq!(subject.0, "unix-process");
 -        assert!(subject.1.contains_key("pid"));
 -        assert!(subject.1.contains_key("uid"));
 +        match subject.0.as_str() {
 +            "unix-session" => assert!(subject.1.contains_key("session-id")),
 +            "unix-process" => {
 +                assert!(subject.1.contains_key("pid"));
 +                assert!(subject.1.contains_key("uid"));
 +                assert!(subject.1.contains_key("start-time"));
 +            }
 +            other => panic!("unexpected subject kind: {other}"),
 +        }
+     }
      #[test]

garcard/src/config.rsmodified

      pub agent_backend: AgentBackendMode,
      pub polkit_object_path: String,
      pub locale: String,
 +    pub backend_healthcheck_secs: u64,
+ }
  impl Default for Config {
              agent_backend: AgentBackendMode::Auto,
              polkit_object_path: "/org/gardesk/Garcard/AuthAgent".to_string(),
              locale: std::env::var("LANG").unwrap_or_else(|_| "en_US.UTF-8".to_string()),
 +            backend_healthcheck_secs: 5,
+         }
+     }
+ }
          if let Some(raw_locale) = std::env::var_os("GARCARD_LOCALE") {
              cfg.locale = raw_locale.to_string_lossy().to_string();
+         }
 +        if let Some(raw_interval) = std::env::var_os("GARCARD_BACKEND_HEALTHCHECK_SECS") {
 +            cfg.backend_healthcheck_secs = parse_positive_secs(&raw_interval.to_string_lossy())
 +                .with_context(|| {
 +                    "Invalid GARCARD_BACKEND_HEALTHCHECK_SECS (expected positive integer seconds)"
 +                })?;
 +        }
          Ok(cfg)
+     }
          if let Some(locale) = file_cfg.locale {
              self.locale = locale;
+         }
 +        if let Some(backend_healthcheck_secs) = file_cfg.backend_healthcheck_secs {
 +            self.backend_healthcheck_secs = parse_positive_secs(&backend_healthcheck_secs)
 +                .with_context(|| {
 +                "Invalid backend_healthcheck_secs in config file (expected positive integer seconds)"
 +            })?;
 +        }
          Ok(())
+     }
      agent_backend: Option<String>,
      polkit_object_path: Option<String>,
      locale: Option<String>,
 +    backend_healthcheck_secs: Option<String>,
+ }
  fn config_path() -> Option<PathBuf> {
      Ok(mode)
+ }
 +fn parse_positive_secs(raw: &str) -> Result<u64> {
 +    let trimmed = raw.trim();
 +    let secs = trimmed
 +        .parse::<u64>()
 +        .with_context(|| format!("failed to parse seconds value: {trimmed}"))?;
 +    if secs == 0 {
 +        anyhow::bail!("seconds must be greater than zero");
 +    }
 +    Ok(secs)
 +}
++
  #[cfg(test)]
  mod tests {
      use super::*;
  agent_backend = "stub"
  polkit_object_path = "/org/gardesk/Garcard/TestAgent"
  locale = "C"
 +backend_healthcheck_secs = "7"
  "#,
+         )
          .expect("parse file config");
              Some("/org/gardesk/Garcard/TestAgent")
          );
          assert_eq!(parsed.locale.as_deref(), Some("C"));
 +        assert_eq!(parsed.backend_healthcheck_secs.as_deref(), Some("7"));
+     }
      #[test]
          let err = AgentBackendMode::from_str("bad").expect_err("should fail");
          assert!(err.to_string().contains("unsupported backend mode"));
+     }
++
 +    #[test]
 +    fn parse_positive_secs_rejects_zero() {
 +        let err = parse_positive_secs("0").expect_err("zero should fail");
 +        assert!(err.to_string().contains("greater than zero"));
 +    }
++
 +    #[test]
 +    fn parse_positive_secs_accepts_positive_integer() {
 +        assert_eq!(parse_positive_secs("9").expect("valid"), 9);
 +    }
+ }

garcard/src/daemon.rsmodified

  use std::os::unix::fs::PermissionsExt;
  use std::path::{Path, PathBuf};
  use std::sync::Arc;
 +use std::time::Duration;
  use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
  use tokio::net::{UnixListener, UnixStream};
  use tokio::sync::mpsc;
          .context("Failed to register SIGTERM handler")?;
      let mut sigint = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::interrupt())
          .context("Failed to register SIGINT handler")?;
 +    let mut sighup = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::hangup())
 +        .context("Failed to register SIGHUP handler")?;
 +    let mut backend_maintenance =
 +        tokio::time::interval(Duration::from_secs(config.backend_healthcheck_secs));
 +    backend_maintenance.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
      tracing::info!(
          socket = %config.socket_path.display(),
          pid = state.status().pid,
          backend = backend.name(),
 +        backend_healthcheck_secs = config.backend_healthcheck_secs,
          "garcard daemon started"
      );
      loop {
          tokio::select! {
 +            _ = backend_maintenance.tick() => {
 +                if let Err(err) = backend.maintain() {
 +                    tracing::warn!(
 +                        error = %err,
 +                        backend = backend.name(),
 +                        "Backend maintenance check failed"
 +                    );
 +                }
 +            }
 +            _ = sighup.recv() => {
 +                tracing::info!("Received SIGHUP; forcing backend reconnect");
 +                if let Err(err) = reconnect_backend(backend.as_mut()) {
 +                    tracing::warn!(error = %err, backend = backend.name(), "Forced backend reconnect failed");
 +                }
 +            }
              _ = sigterm.recv() => {
                  tracing::info!("Received SIGTERM");
                  break;
      Ok(())
+ }
 +fn reconnect_backend(backend: &mut dyn AuthAgentBackend) -> Result<()> {
 +    backend.unregister()?;
 +    backend.register()?;
 +    Ok(())
 +}
++
  fn init_backend(config: &Config, auth_state: Arc<AuthState>) -> Result<Box<dyn AuthAgentBackend>> {
      match config.agent_backend {
          AgentBackendMode::Stub => {
  #[cfg(test)]
  mod tests {
      use super::*;
 +    use anyhow::Result as AnyResult;
 +    use std::sync::Arc;
 +    use std::sync::atomic::{AtomicUsize, Ordering};
      fn fake_state() -> RuntimeState {
          RuntimeState::new("/tmp/garcard-test.sock".to_string(), "test-backend")
              agent_backend: AgentBackendMode::Auto,
              polkit_object_path: "invalid path".to_string(),
              locale: "C".to_string(),
 +            backend_healthcheck_secs: 5,
          };
          let backend = init_backend(&config, Arc::new(AuthState::default()))
              .expect("auto mode should fall back");
          assert_eq!(backend.name(), "stub-polkit-agent");
+     }
++
 +    struct TrackingBackend {
 +        unregister_calls: Arc<AtomicUsize>,
 +        register_calls: Arc<AtomicUsize>,
 +    }
++
 +    impl AuthAgentBackend for TrackingBackend {
 +        fn name(&self) -> &'static str {
 +            "tracking-backend"
 +        }
++
 +        fn register(&mut self) -> AnyResult<()> {
 +            self.register_calls.fetch_add(1, Ordering::Relaxed);
 +            Ok(())
 +        }
++
 +        fn unregister(&mut self) -> AnyResult<()> {
 +            self.unregister_calls.fetch_add(1, Ordering::Relaxed);
 +            Ok(())
 +        }
 +    }
++
 +    #[test]
 +    fn reconnect_backend_calls_unregister_then_register() {
 +        let unregister_calls = Arc::new(AtomicUsize::new(0));
 +        let register_calls = Arc::new(AtomicUsize::new(0));
 +        let mut backend = TrackingBackend {
 +            unregister_calls: Arc::clone(&unregister_calls),
 +            register_calls: Arc::clone(&register_calls),
 +        };
++
 +        reconnect_backend(&mut backend).expect("reconnect");
 +        assert_eq!(unregister_calls.load(Ordering::Relaxed), 1);
 +        assert_eq!(register_calls.load(Ordering::Relaxed), 1);
 +    }
+ }