Tauri Network Manager Plugin

Linux-first Tauri plugin to manage network state, Wi-Fi, and VPN through NetworkManager over D-Bus.

Table of Contents

• Features
• Architecture
• Requirements
• Installation
• Permissions
• Quick Start
• API Reference
• TypeScript Usage
• Event System
• Error Handling
• Caching
• Types
• Package Exports
• Testing & Build
• Contributing

Features

Wi-Fi

• Scan & list nearby access points with signal strength and security detection
• Connect to open / WEP / WPA-PSK / WPA2-PSK / WPA3-PSK / WPA-EAP networks
• Disconnect from current Wi-Fi
• List and delete saved Wi-Fi connections
• Request explicit scans

VPN

• List, create, update, delete VPN profiles (OpenVPN, WireGuard, L2TP, PPTP, SSTP, IKEv2, FortiSSL, OpenConnect, Generic)
• Connect / disconnect VPN by UUID
• Read current VPN status, gateway, IP configuration

Network State

• Read current active network (Ethernet / Wi-Fi) — SSID, IP, MAC, signal, security
• Enable / disable wireless and global networking
• Check wireless hardware availability

Monitoring

• Bandwidth stats (download/upload speed, total bytes, uptime)
• Real-time events via Tauri's event system:
  • network-changed — network state transition
  • vpn-changed, vpn-connected, vpn-disconnected, vpn-failed

Architecture

flowchart TB
    subgraph Frontend["Tauri Frontend (TypeScript)"]
        TS["guest-js/index.ts<br/>invoke() / listen()"]
    end

    subgraph IPC["Tauri Bridge"]
        IPC_BRIDGE["Plugin IPC"]
    end

    subgraph Rust["Rust Plugin (tauri-plugin-network-manager)"]
        direction TB
        CMDS["commands.rs<br/>19 #[tauri::command]"]
        DESKTOP["desktop.rs<br/>D-Bus logic"]
        HELPERS["nm_helpers.rs<br/>security detection"]
        STATS["network_stats.rs<br/>bandwidth tracker"]
        LIB["lib.rs<br/>state mgmt · caching<br/>event emitter"]
        ERR["error.rs<br/>typed errors"]
        MODELS["models.rs<br/>data structures"]

        CMDS --> DESKTOP
        DESKTOP --> HELPERS
        DESKTOP --> STATS
        LIB --> CMDS
        DESKTOP --> ERR
        DESKTOP --> MODELS
    end

    subgraph NM["NetworkManager (D-Bus System Bus)"]
        NM_MAIN["org.freedesktop.NetworkManager<br/>AddAndActivateConnection<br/>ActivateConnection<br/>DeactivateConnection"]
        NM_SETTINGS["org.freedesktop.NetworkManager.Settings<br/>AddConnection · Update · Delete<br/>ListConnections"]
        NM_DEVICE["org.freedesktop.NetworkManager.Device<br/>DeviceType · HwAddress · Ip4Config"]
        NM_WIFI["org.freedesktop.NetworkManager.Device.Wireless<br/>AccessPoints · ActiveAccessPoint<br/>RequestScan"]
        NM_AP["org.freedesktop.NetworkManager.AccessPoint<br/>Ssid · Strength · Flags<br/>WpaFlags · RsnFlags · KeyMgmt"]
        NM_ACTIVE["org.freedesktop.NetworkManager.Connection.Active<br/>State · Type · Devices · Uuid"]
    end

    Frontend <--> IPC
    IPC <--> Rust
    DESKTOP -- "zbus 4 (blocking)" --> NM_MAIN
    DESKTOP --> NM_SETTINGS
    DESKTOP --> NM_DEVICE
    DESKTOP --> NM_WIFI
    DESKTOP --> NM_AP
    DESKTOP --> NM_ACTIVE

Key modules

| Module | Responsibility | |---|---| | lib.rs | Tauri plugin entry point, state management (Arc<RwLock>), network change event emitter with 250 ms debounce | | desktop.rs | All D-Bus calls via zbus 4: network state, Wi-Fi scan/connect, VPN CRUD, signal listening | | commands.rs | 19 #[tauri::command] functions bridging IPC to desktop.rs | | nm_helpers.rs | Security type detection (KeyMgmt / WpaFlags / RsnFlags), SSID byte→string conversion, connectivity check | | network_stats.rs | Bandwidth tracker reading /sys/class/net/<iface>/statistics | | error.rs | Typed error enum with thiserror, D-Bus error mapping | | models.rs | All data structures: NetworkInfo, WiFiConnectionConfig, VpnProfile, etc. |

Requirements

• Linux with NetworkManager running on D-Bus system bus
• Tauri 2 project
• Rust 1.77.2+
• System D-Bus libraries (libdbus-1-dev or equivalent)

Installation

Cargo

[dependencies]
tauri-plugin-network-manager = { git = "https://github.com/Vasak-OS/tauri-plugin-network-manager" }

NPM (guest bindings)

bun add @vasakgroup/plugin-network-manager
# or
npm install @vasakgroup/plugin-network-manager
# or
pnpm add @vasakgroup/plugin-network-manager

Register the plugin

// src-tauri/src/lib.rs
fn main() {
    tauri::Builder::default()
        .plugin(tauri_plugin_network_manager::init())
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

Permissions

By default the plugin allows read + Wi-Fi connect/disconnect operations. VPN mutations are opt-in.

Default permission set

// src-tauri/capabilities/default.json
{
  "identifier": "default",
  "windows": ["main"],
  "permissions": [
    "network-manager:default"
  ]
}

The default set includes:

• get-network-state, list-wifi-networks, rescan-wifi
• connect-to-wifi, disconnect-from-wifi
• get-saved-wifi-networks, delete-wifi-connection
• toggle-network-state, get-wireless-enabled, set-wireless-enabled
• is-wireless-available, list-vpn-profiles, get-vpn-status

VPN management permission

{
  "permissions": [
    "network-manager:vpn_management",
    // or individually:
    "network-manager:allow-connect-vpn",
    "network-manager:allow-disconnect-vpn",
    "network-manager:allow-create-vpn-profile",
    "network-manager:allow-update-vpn-profile",
    "network-manager:allow-delete-vpn-profile"
  ]
}

Quick Start

Wi-Fi — scan and connect

import {
  listWifiNetworks,
  connectToWifi,
  disconnectFromWifi,
  WiFiSecurityType,
} from '@vasakgroup/plugin-network-manager';

// 1. Scan available networks
const networks = await listWifiNetworks();
console.log(networks.map(n => `${n.ssid} (${n.signal_strength}%)`));

// 2. Connect to a WPA2-PSK network
await connectToWifi({
  ssid: 'MyNetwork',
  password: 'supersecret',
  securityType: WiFiSecurityType.WPA2_PSK,
});

// 3. Disconnect
await disconnectFromWifi();

VPN — create, connect, and listen

import {
  createVpnProfile,
  connectVpn,
  getVpnStatus,
  disconnectVpn,
  deleteVpnProfile,
} from '@vasakgroup/plugin-network-manager';
import { listen } from '@tauri-apps/api/event';
import type { VpnEventPayload } from '@vasakgroup/plugin-network-manager';

// Listen for VPN state changes
const unlisten = await listen<VpnEventPayload>('vpn-changed', (e) => {
  console.log('VPN state:', e.payload.status.state);
});

// Create and connect
const profile = await createVpnProfile({
  id: 'Office VPN',
  vpn_type: 'wire-guard',
  settings: { endpoint: 'vpn.example.com:51820' },
  secrets: { private_key: '***' },
});

await connectVpn(profile.uuid);
console.log(await getVpnStatus());

// Cleanup
await disconnectVpn(profile.uuid);
await deleteVpnProfile(profile.uuid);
unlisten();

Network monitoring

import { getNetworkStats } from '@vasakgroup/plugin-network-manager';

const stats = await getNetworkStats();
console.log({
  download: `${stats.download_speed} B/s`,
  upload: `${stats.upload_speed} B/s`,
  totalDown: `${(stats.total_downloaded / 1e6).toFixed(1)} MB`,
  uptime: `${stats.connection_duration}s`,
});

API Reference

getCurrentNetworkState(): Promise<NetworkInfo>

Returns the currently active network connection info, or a default if disconnected.

listWifiNetworks(options?: ListWifiNetworksOptions): Promise<NetworkInfo[]>

Scans and returns all visible access points, deduplicated by SSID, sorted by signal strength.

| Option | Type | Default | Description | |---|---|---|---| | forceRefresh | boolean | false | Bypass in-memory cache | | ttlMs | number | 3000 | Cache TTL in milliseconds (250–30000) |

rescanWifi(): Promise<NetworkInfo[]>

Triggers a RequestScan D-Bus call on all wireless devices and returns fresh results.

connectToWifi(config: ConnectToWifiInput | WiFiConnectionConfig): Promise<void>

Accepts both camelCase (frontend-friendly) and snake_case (Rust wire) formats.

| Field | Type | Required | Description | |---|---|---|---| | ssid | string | yes | Network SSID | | password | string | no | PSK / password | | securityType / security_type | WiFiSecurityType | yes | See WiFiSecurityType | | username | string | no | WPA-EAP identity |

Supported security types:

| Value | D-Bus key-mgmt | Notes | |---|---|---| | None | — | Open network | | Wep | none | Static WEP with wep-key0 | | WpaPsk | wpa-psk | WPA1-PSK | | Wpa2Psk | wpa-psk + proto=["rsn"] | WPA2-PSK | | Wpa3Psk | sae | WPA3-SAE | | WpaEap | wpa-eap | Enterprise WPA-EAP |

disconnectFromWifi(): Promise<void>

Deactivates the active Wi-Fi connection.

getSavedWifiNetworks(): Promise<NetworkInfo[]>

Returns saved Wi-Fi profiles (known networks) from NM settings, with SSID and detected security type.

deleteWifiConnection(ssid: string): Promise<void>

Deletes the first saved connection matching the given SSID.

toggleNetwork(enabled: boolean): Promise<boolean>

Enables or disables all networking. Returns the new state.

getWirelessEnabled(): Promise<boolean>

Returns whether Wi-Fi radio is enabled.

setWirelessEnabled(enabled: boolean): Promise<void>

Enables or disables Wi-Fi radio.

isWirelessAvailable(): Promise<boolean>

Returns true if at least one Wi-Fi adapter is present.

listVpnProfiles(): Promise<VpnProfile[]>

Returns all VPN profiles sorted by ID.

getVpnStatus(): Promise<VpnStatus>

Returns the current active VPN state, profile info, gateway, and IP.

connectVpn(uuid: string): Promise<void>

Activates a VPN by UUID. Throws VpnAlreadyConnected if already connected to the same profile.

disconnectVpn(uuid?: string): Promise<void>

Deactivates a VPN. If uuid is omitted, deactivates the currently active VPN (VpnNotActive if none).

createVpnProfile(config: VpnCreateInput): Promise<VpnProfile>

Creates a new VPN profile in NM settings. Requires vpn_management permission.

| Field | Type | Required | Description | |---|---|---|---| | id | string | yes | Profile display name | | vpn_type | VpnType | yes | See VpnType | | autoconnect | boolean | no | Auto-connect on boot | | username | string | no | VPN username | | gateway | string | no | Remote gateway address | | ca_cert_path | string | no | CA certificate path | | user_cert_path | string | no | User certificate path | | private_key_path | string | no | Private key path | | private_key_password | string | no | Private key passphrase | | settings | Record<string, string> | no | Custom VPN settings | | secrets | Record<string, string> | no | Custom VPN secrets (e.g. psk, private_key) |

updateVpnProfile(config: VpnUpdateInput): Promise<VpnProfile>

Updates an existing VPN profile. All fields except uuid are optional.

| Field | Type | Description | |---|---|---| | uuid | string | Profile UUID to update (required) | | id | string | New display name | | autoconnect | boolean | New auto-connect preference | | username | string | New username | | gateway | string | New remote address | | ca_cert_path | string | New CA cert path | | user_cert_path | string | New user cert path | | private_key_path | string | New private key path | | private_key_password | string | New passphrase | | settings | Record<string, string> | Merged into existing settings | | secrets | Record<string, string> | Merged into existing secrets |

deleteVpnProfile(uuid: string): Promise<void>

Deletes a VPN profile by UUID.

getNetworkStats(): Promise<NetworkStats>

Returns bandwidth statistics for the active interface.

interface NetworkStats {
  download_speed: number;    // bytes/sec
  upload_speed: number;      // bytes/sec
  total_downloaded: number;  // bytes
  total_uploaded: number;    // bytes
  connection_duration: number; // seconds
  interface: string;         // e.g. "wlan0"
}

getNetworkInterfaces(): Promise<string[]>

Returns all non-loopback network interface names.

Event System

The plugin emits Tauri events when network state changes, with a 250 ms debounce window to coalesce rapid transitions.

Events

| Event | Payload | When | |---|---|---| | network-changed | NetworkInfo | Any network state transition | | vpn-changed | VpnEventPayload | VPN state transition | | vpn-connected | VpnEventPayload | Transition to Connected | | vpn-disconnected | VpnEventPayload | Transition to Disconnected | | vpn-failed | VpnEventPayload | Transition to Failed |

Example

import { listen } from '@tauri-apps/api/event';
import type { NetworkInfo, VpnEventPayload } from '@vasakgroup/plugin-network-manager';

// Network changes
const unlistenNet = await listen<NetworkInfo>('network-changed', (event) => {
  const n = event.payload;
  const status = n.is_connected ? `connected to ${n.ssid}` : 'disconnected';
  console.log(`[${n.connection_type}] ${status} (${n.ip_address})`);
});

// VPN failures
const unlistenFail = await listen<VpnEventPayload>('vpn-failed', (event) => {
  console.error(`VPN failed: ${event.payload.reason}`);
});

// Cleanup when leaving component
// unlistenNet();
// unlistenFail();

Error Handling

All commands throw a typed NetworkManagerError with a code property:

import { connectToWifi, NetworkManagerErrorCode } from '@vasakgroup/plugin-network-manager';

try {
  await connectToWifi({ ssid: '...', password: '...', securityType: 'wpa2-psk' });
} catch (e) {
  if (e.code === NetworkManagerErrorCode.CONNECTION_FAILED) {
    showToast('Connection failed. Check password.');
  } else if (e.code === NetworkManagerErrorCode.UNSUPPORTED_SECURITY) {
    showToast('This security type is not supported.');
  } else {
    showToast(`Unexpected error: ${e.message}`);
  }
}

Error codes

| Code | Meaning | |---|---| | NOT_INITIALIZED | Plugin not initialized | | NO_CONNECTION | No active network | | PERMISSION_DENIED | Capability not granted | | UNSUPPORTED_SECURITY | Security type not implemented | | CONNECTION_FAILED | D-Bus connection call failed | | NETWORK_NOT_FOUND | SSID not in saved networks | | OPERATION_FAILED | Generic failure | | VPN_PROFILE_NOT_FOUND | UUID not in settings | | VPN_ALREADY_CONNECTED | Already connected to that profile | | VPN_AUTH_FAILED | Secret/authentication error | | VPN_INVALID_CONFIG | Bad profile parameters | | VPN_ACTIVATION_FAILED | ActivateConnection D-Bus error | | VPN_PLUGIN_UNAVAILABLE | NM plugin not found | | VPN_NOT_ACTIVE | No active VPN to disconnect | | UNKNOWN | Fallback |

Caching

Wi-Fi scan results are cached in-memory for 3 seconds by default to avoid redundant D-Bus calls.

// Bypass cache
const fresh = await listWifiNetworks({ forceRefresh: true });

// Custom TTL (500 ms)
const fast = await listWifiNetworks({ ttlMs: 500 });

// rescanWifi always invalidates cache and returns fresh data

Types

WiFiSecurityType

type WiFiSecurityType =
  | 'none'
  | 'wep'
  | 'wpa-psk'
  | 'wpa-eap'
  | 'wpa2-psk'
  | 'wpa3-psk';

VpnType

type VpnType =
  | 'open-vpn'
  | 'wire-guard'
  | 'l2tp'
  | 'pptp'
  | 'sstp'
  | 'ikev2'
  | 'fortisslvpn'
  | 'open-connect'
  | 'generic';

VpnConnectionState

type VpnConnectionState =
  | 'disconnected'
  | 'connecting'
  | 'connected'
  | 'disconnecting'
  | 'failed'
  | 'unknown';

NetworkInfo

interface NetworkInfo {
  name: string;
  ssid: string;
  connection_type: string;      // "wifi" | "Ethernet" | "Unknown"
  icon: string;                  // icon name for the UI
  ip_address: string;            // "0.0.0.0" when disconnected
  mac_address: string;
  signal_strength: number;       // 0–100
  security_type: WiFiSecurityType;
  is_connected: boolean;
}

VpnProfile

interface VpnProfile {
  id: string;
  uuid: string;
  vpn_type: VpnType;
  interface_name: string | null;
  autoconnect: boolean;
  editable: boolean;
  last_error: string | null;
}

VpnStatus

interface VpnStatus {
  state: VpnConnectionState;
  active_profile_id: string | null;
  active_profile_uuid: string | null;
  active_profile_name: string | null;
  ip_address: string | null;
  gateway: string | null;
  since_unix_ms: number | null;
}

VpnEventPayload

interface VpnEventPayload {
  status: VpnStatus;
  profile: VpnProfile | null;
  reason: string | null;  // populated on 'vpn-failed'
}

Package Exports

The NPM package provides ESM, CJS, and TypeScript declarations:

{
  "main": "./dist-js/index.cjs",
  "module": "./dist-js/index.js",
  "types": "./dist-js/index.d.ts",
  "exports": {
    "types": "./dist-js/index.d.ts",
    "import": "./dist-js/index.js",
    "require": "./dist-js/index.cjs"
  }
}

Testing & Build

# Build the Rust crate
cargo build

# Run Rust tests
cargo test

# Build NPM guest package
bun run build

# Run smoke tests (requires Tauri project)
bun run test

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feat/my-feature)
3. Commit your changes (git commit -am 'feat: add ...')
4. Push (git push origin feat/my-feature)
5. Open a Pull Request

Development tips

• Use RUST_LOG=debug or RUST_LOG=trace to enable D-Bus call logging
• Monitor NM D-Bus traffic: busctl monitor org.freedesktop.NetworkManager
• Test Wi-Fi connection flow: nmcli dev wifi list then nmcli connection add ...

License

GPL-3.0-or-later — see LICENSE.