feat(openconnect): add optional integration crate

Add a focused aetheris-openconnect crate that isolates libopenconnect FFI behind safe Rust session, config, event, and error types.

Expose the crate behind an optional aetheris-app openconnect feature, wire it into the workspace, and document the architecture and local build requirements for the system-libopenconnect feature.

Author: leandromqrs

ARCHITECTURE.md

@@ -10,6 +10,7 @@ flowchart TD
   UI --> Relm[Relm4 App Component]
   Relm --> Commands[Async Commands and Streams]
   Commands --> KubeCrate[aetheris-kube]
+  Commands -. optional VPN .-> OpenConnectCrate[aetheris-openconnect]
   KubeCrate --> Kubeconfig[Kubeconfig]
   KubeCrate --> Api[Kubernetes / OpenShift API]
   Relm --> Store[ProjectStore]
@@ -18,7 +19,7 @@ flowchart TD
   VTE --> Commands
 ```
 
-`aetheris-app` owns windows, widgets, user state, and persistence of Aetheris projects. `aetheris-kube` owns kubeconfig parsing, Kubernetes clients, discovery, list/watch, mutations, logs, exec, port-forwarding, metrics, and resource details.
+`aetheris-app` owns windows, widgets, user state, and persistence of Aetheris projects. `aetheris-kube` owns kubeconfig parsing, Kubernetes clients, discovery, list/watch, mutations, logs, exec, port-forwarding, metrics, and resource details. `aetheris-openconnect` is an optional native integration crate for libopenconnect; it isolates C FFI and exposes a Rust API for future VPN workflows.
 
 ## Crate Boundaries
 
@@ -40,10 +41,17 @@ flowchart LR
     Ops[Logs exec port-forward mutations]
   end
 
+  subgraph OpenConnect["aetheris-openconnect"]
+    SafeApi[Safe Rust API]
+    Ffi[libopenconnect FFI]
+  end
+
   Widgets --> State
   State --> Commands
   State --> Streams
   Commands --> Manager
+  Commands -. optional .-> SafeApi
+  SafeApi --> Ffi
   Streams --> Manager
   Manager --> Session
   Session --> Resources
@@ -52,7 +60,7 @@ flowchart LR
   Projects --> State
 ```
 
-The backend crate must not import GTK, Adwaita, Relm4, VTE, or application widgets. Shared data crosses the boundary through DTOs exported from `aetheris-kube::types`.
+The backend crate must not import GTK, Adwaita, Relm4, VTE, or application widgets. Shared data crosses the boundary through DTOs exported from `aetheris-kube::types`. Native C integrations are kept out of both UI widgets and `aetheris-kube`; each integration gets a focused crate such as `aetheris-openconnect`, with `unsafe` declarations confined to its FFI module.
 
 ## Application Lifecycle
 

CONTRIBUTING.md

@@ -13,6 +13,16 @@ sudo dnf install -y \
   openssl-devel
 ```
 
+OpenConnect integration is optional while the VPN UI is under development. To
+build it locally, install the libopenconnect development files and enable the
+feature:
+
+```sh
+sudo dnf install -y openconnect-devel
+cargo check -p aetheris-openconnect --features system-libopenconnect
+cargo check -p aetheris-app --features openconnect
+```
+
 Run the app:
 
 ```sh
@@ -56,6 +66,7 @@ Aetheris has two Rust crates:
 
 - `aetheris-kube` — pure Kubernetes backend. It must not depend on GTK, Relm4, Libadwaita, or VTE.
 - `aetheris-app` — Relm4/GTK4 application. It owns UI state, widgets, project persistence, and command wiring.
+- `aetheris-openconnect` — optional libopenconnect integration. It owns C FFI and exposes only safe Rust types to the app.
 
 See [ARCHITECTURE.md](ARCHITECTURE.md) for diagrams and module responsibilities.
 

Cargo.lock

@@ -1,6 +1,10 @@
 [workspace]
 resolver = "2"
-members = ["crates/aetheris-app", "crates/aetheris-kube"]
+members = [
+    "crates/aetheris-app",
+    "crates/aetheris-kube",
+    "crates/aetheris-openconnect",
+]
 
 [workspace.package]
 version = "1.3.0"

Cargo.toml

@@ -53,8 +53,16 @@ resources = [
   "../../po/pt_BR/LC_MESSAGES/org.luminusos.Aetheris.mo",
 ]
 
+[features]
+default = []
+openconnect = [
+  "dep:aetheris-openconnect",
+  "aetheris-openconnect/system-libopenconnect",
+]
+
 [dependencies]
 aetheris-kube = { path = "../aetheris-kube" }
+aetheris-openconnect = { path = "../aetheris-openconnect", optional = true }
 anyhow = "1"
 dirs = "6"
 futures = "0.3"

crates/aetheris-app/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "aetheris-openconnect"
+description = "OpenConnect integration layer for Aetheris"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+links = "openconnect"
+
+[features]
+default = []
+system-libopenconnect = []
+
+[dependencies]
+thiserror.workspace = true
+
+[build-dependencies]
+pkg-config = "0.3"

crates/aetheris-openconnect/Cargo.toml

@@ -0,0 +1,18 @@
+fn main() {
+    println!("cargo:rerun-if-env-changed=PKG_CONFIG_PATH");
+    println!("cargo:rerun-if-env-changed=OPENCONNECT_NO_PKG_CONFIG");
+
+    if std::env::var_os("CARGO_FEATURE_SYSTEM_LIBOPENCONNECT").is_none() {
+        return;
+    }
+
+    if std::env::var_os("OPENCONNECT_NO_PKG_CONFIG").is_some() {
+        println!("cargo:rustc-link-lib=openconnect");
+        return;
+    }
+
+    pkg_config::Config::new()
+        .atleast_version("8.20")
+        .probe("openconnect")
+        .expect("system-libopenconnect requires libopenconnect development files");
+}

crates/aetheris-openconnect/build.rs

@@ -0,0 +1,21 @@
+use std::ffi::NulError;
+
+#[derive(Debug, thiserror::Error)]
+pub enum OpenConnectError {
+    #[error("OpenConnect support was built without libopenconnect")]
+    NotLinked,
+    #[error("{field} contains an interior NUL byte")]
+    InteriorNul {
+        field: &'static str,
+        #[source]
+        source: NulError,
+    },
+    #[error("libopenconnect initialization failed with code {0}")]
+    InitFailed(i32),
+    #[error("unable to allocate OpenConnect session")]
+    AllocationFailed,
+    #[error("{operation} failed with code {code}")]
+    OperationFailed { operation: &'static str, code: i32 },
+}
+
+pub type Result<T> = std::result::Result<T, OpenConnectError>;

crates/aetheris-openconnect/src/error.rs

@@ -0,0 +1,35 @@
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum OpenConnectEvent {
+    Progress {
+        level: ProgressLevel,
+        message: String,
+    },
+    CertificateValidationRequired {
+        reason: String,
+    },
+    AuthenticationFormRequired,
+    Connected,
+    Disconnected,
+    Error(String),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ProgressLevel {
+    Error,
+    Info,
+    Debug,
+    Trace,
+    Unknown(i32),
+}
+
+impl From<i32> for ProgressLevel {
+    fn from(value: i32) -> Self {
+        match value {
+            0 => Self::Error,
+            1 => Self::Info,
+            2 => Self::Debug,
+            3 => Self::Trace,
+            other => Self::Unknown(other),
+        }
+    }
+}

crates/aetheris-openconnect/src/events.rs

@@ -0,0 +1,43 @@
+#![cfg(feature = "system-libopenconnect")]
+
+use std::ffi::{c_char, c_int, c_void};
+
+#[repr(C)]
+pub struct OpenconnectInfo {
+    _private: [u8; 0],
+}
+
+pub type ValidatePeerCertCallback =
+    unsafe extern "C" fn(privdata: *mut c_void, reason: *const c_char) -> c_int;
+pub type WriteNewConfigCallback =
+    unsafe extern "C" fn(privdata: *mut c_void, buf: *const c_char, buflen: c_int) -> c_int;
+pub type ProcessAuthFormCallback =
+    unsafe extern "C" fn(privdata: *mut c_void, form: *mut c_void) -> c_int;
+
+unsafe extern "C" {
+    pub fn openconnect_init_ssl() -> c_int;
+    pub fn openconnect_get_version() -> *const c_char;
+
+    pub fn openconnect_vpninfo_new(
+        useragent: *const c_char,
+        validate_peer_cert: Option<ValidatePeerCertCallback>,
+        write_new_config: Option<WriteNewConfigCallback>,
+        process_auth_form: Option<ProcessAuthFormCallback>,
+        progress: *mut c_void,
+        privdata: *mut c_void,
+    ) -> *mut OpenconnectInfo;
+
+    pub fn openconnect_vpninfo_free(vpninfo: *mut OpenconnectInfo);
+    pub fn openconnect_parse_url(vpninfo: *mut OpenconnectInfo, url: *const c_char) -> c_int;
+    pub fn openconnect_set_protocol(
+        vpninfo: *mut OpenconnectInfo,
+        protocol: *const c_char,
+    ) -> c_int;
+    pub fn openconnect_set_cafile(vpninfo: *mut OpenconnectInfo, cafile: *const c_char) -> c_int;
+    pub fn openconnect_set_loglevel(vpninfo: *mut OpenconnectInfo, level: c_int);
+    pub fn openconnect_set_system_trust(vpninfo: *mut OpenconnectInfo, val: u32);
+    pub fn openconnect_disable_ipv6(vpninfo: *mut OpenconnectInfo) -> c_int;
+    pub fn openconnect_disable_dtls(vpninfo: *mut OpenconnectInfo) -> c_int;
+    pub fn openconnect_get_protocol(vpninfo: *mut OpenconnectInfo) -> *const c_char;
+    pub fn openconnect_get_connect_url(vpninfo: *mut OpenconnectInfo) -> *const c_char;
+}