Remote Desktop: Wayland compatibility problems and macOS screen capture not implemented

[antoncxx]

Wayland — Known Issues

1. Screen capture requires session user UID (blocks root deployments)

KWin (KDE Plasma 6) and most other Wayland compositors restrict zwlr_screencopy_manager_v1 to processes whose UID matches the session user. When the agent runs as root, the compositor simply does not advertise the protocol, making screen capture impossible.

Affected compositors: KWin (KDE Plasma 6), likely others
Not affected: sway, hyprland, labwc, river (these advertise screencopy to all clients)
Current behaviour: the pseudo-RD service is not advertised when screencopy negotiation fails, so the failure is silent rather than broken — but remote desktop is unavailable.

Potential solutions (in order of preference):

• Run the agent as the session user and grant network capabilities via setcap cap_net_raw,cap_net_admin+eip — requires removing the hard is_root() exit check and adding the session user to the input group for uinput access
• Spawn a small privileged-drop helper binary that runs as the session user, connects to Wayland, and streams frames back over a Unix socket
• Implement xdg-desktop-portal + PipeWire screen capture — compositor-agnostic but shows a one-time user-approval dialog that cannot be displayed in the browser UI; requires the user to be physically present at the machine for first-run approval

---

2. GNOME / Mutter: zwlr_screencopy_manager_v1 not implemented

GNOME's compositor (Mutter) does not implement the wlr-screencopy protocol at all. Remote desktop is therefore unavailable on any GNOME Wayland session regardless of which user the agent runs as.

Affected sessions: GNOME on Wayland (Ubuntu 22.04+, Fedora Workstation, etc.)
Potential solution: xdg-desktop-portal + PipeWire (org.freedesktop.portal.ScreenCast) — this is the only screencopy path Mutter supports, but it has the first-run dialog problem described above.

---

3. Clipboard sync unavailable on pure Wayland

copypasta's ClipboardContext attempts an XCB/X11 handshake regardless of the active display protocol. On a pure Wayland session without XWayland, this always fails.

Current behaviour: clipboard initialisation failure is caught and clipboard sync is disabled for the session (graceful degradation). Remote desktop still opens; only clipboard paste/copy is non-functional.
Potential solution: add Wayland clipboard support via wl-clipboard or switch to the arboard crate which has native Wayland support.

---

4. Input injection (/dev/uinput) requires group membership

/dev/uinput is owned by root and the input group. When the agent is moved to run as the session user (the fix for issue 1), the user must be a member of the input group for uinput-based input injection to work.

Current behaviour: works when running as root; breaks if moved to session user without group setup.
Required: add the session user to the input group, or document this as a post-install step.

---

macOS — Not Implemented + Anticipated Issues

5. Screen capture not implemented

macOS falls through to the "Screen capture is not supported on this platform" error path. No capturer exists for Quartz/CoreGraphics.

Required implementation: CGDisplayCreateImage() (CoreGraphics, via the core-graphics crate) or ScreenCaptureKit (macOS 12.3+, stricter but modern).

---

6. Screen capture will require session context + TCC permission (same root problem, different mechanism)

Even once implemented, a root launchd daemon will face two separate blocks:

• WindowServer session access — the WindowServer is owned by the GUI login session. A daemon launched outside that session cannot connect to it regardless of UID.
• TCC Screen Recording permission — since macOS 10.15, all screen capture requires explicit user approval in System Settings → Privacy & Security → Screen Recording. Enforced by the TCC daemon against the binary's code-signing identity; root UID does not bypass it.

Consequence: the same architectural problem as Wayland — the agent must either run as a login item in the user's GUI session, or use a session-context helper process. Running as root is insufficient.

---

Summary

Platform	Screen capture	Input injection	Clipboard
Linux / X11 (agent as root)	✅ works	✅ works	✅ works
Linux / Wayland, KDE/KWin (agent as root)	❌ UID restriction	✅ uinput works	❌ X11 only
Linux / Wayland, GNOME (agent as root)	❌ protocol missing	✅ uinput works	❌ X11 only
Linux / Wayland (agent as session user)	✅ works (KDE/sway/hyprland)	⚠️ needs input group	❌ X11 only
macOS	❌ not implemented	❓ not tested	❓ not tested
Windows	✅ GDI works	✅ works	✅ works

[antoncxx]

The agent requires root for exactly two things:

1. Raw packet capture — libpcap / AF_PACKET sockets require CAP_NET_RAW and CAP_NET_ADMIN.
2. uinput input injection — /dev/uinput is root:input; root bypasses the group check.

Everything else (Wayland screencopy, clipboard, the control channel, storage) works fine as an unprivileged user. Running as root is a blunt instrument that actively breaks Wayland and will break macOS once screen capture is implemented there.

The fix: setcap + session-user deployment

Grant the two needed capabilities at file level so the binary can run as any unprivileged user:

setcap cap_net_raw,cap_net_admin+eip /usr/local/bin/wallguard

libpcap checks for these capabilities at open time and does not require UID 0. The agent then runs as the desktop session user, which satisfies the KWin UID restriction for zwlr_screencopy_manager_v1 and will satisfy the macOS WindowServer session requirement once that is implemented.

Input injection via /dev/uinput requires the session user to be a member of the input group. The post-install script adds them:

usermod -aG input <session-user>

---

Code changes required

1. Remove the Unix root check — wallguard/src/main.rs:42

The #[cfg(unix)] block inside check_privileges() must be removed. The Windows block (is_elevated) stays — Administrator is still required on Windows for WinPcap/Npcap.

// Remove this block entirely:
#[cfg(unix)]
{
    if !nix::unistd::Uid::effective().is_root() {
        println!("This program must be run as root. Exiting ...");
        std::process::exit(-1);
    }
}

---

2. Fix Wayland socket connection — wallguard/src/remote_desktop/screen_capturer.rs:321

Connection::connect_to_env() fails when XDG_RUNTIME_DIR is not set in the process environment, which is common for systemd services. Replace with an explicit socket path using the same uid-fallback logic already in client_data/platform.rs:

// Replace:
let conn = Connection::connect_to_env().handle_err(location!())?;

// With:
let socket_path = wayland_socket_path()
    .ok_or("cannot resolve Wayland socket path")
    .handle_err(location!())?;
let stream = std::os::unix::net::UnixStream::connect(&socket_path).handle_err(location!())?;
stream.set_nonblocking(true).handle_err(location!())?;
let conn = Connection::from_socket(stream).handle_err(location!())?;

Where wayland_socket_path() is:

fn wayland_socket_path() -> Option<String> {
    let display = std::env::var("WAYLAND_DISPLAY").ok()?;
    if display.starts_with('/') {
        return Some(display);
    }
    let runtime = std::env::var("XDG_RUNTIME_DIR")
        .ok()
        .or_else(|| Some(format!("/run/user/{}", nix::unistd::getuid())))?;
    Some(format!("{runtime}/{display}"))
}

Also remove the X11 fallback in create_capturer() for the Wayland branch. If has_wayland_display() is true and WaylandCapturer::new() fails, the failure is real (compositor lacks screencopy), not an X11-fallback situation.

---

3. Gate pseudo-RD advertisement on a real screencopy probe — wallguard/src/netinfo/service/pseudo_rd.rs:65

is_rd_available() currently returns has_wayland_display() for pure Wayland — a socket-existence check that returns true even when KWin refuses screencopy to the running UID. The service gets advertised and then fails when the client tries to open a session.

Add a probe function to screen_capturer.rs, re-export it through remote_desktop/mod.rs, and call it from pseudo_rd.rs:

// screen_capturer.rs — new function:
pub(crate) fn screen_capture_available() -> bool {
    #[cfg(target_os = "linux")]
    {
        use crate::client_data::platform::has_wayland_display;
        if has_wayland_display() {
            return wayland::WaylandCapturer::new().is_ok();
        }
        x11rb::connect(None).is_ok()
    }
    #[cfg(not(target_os = "linux"))]
    { create_capturer().is_ok() }
}

// remote_desktop/mod.rs — re-export:
pub(crate) use screen_capturer::screen_capture_available;

// pseudo_rd.rs — replace has_wayland_display() call:
return crate::remote_desktop::screen_capture_available();

This makes the discovery cycle self-correcting: if the compositor later gains screencopy support the next 5-minute cycle picks it up without restarting the agent.

---

4. Replace copypasta with arboard — wallguard/src/remote_desktop/messages.rs

copypasta unconditionally attempts an XCB/X11 connection, crashing session open on pure Wayland. arboard supports X11, Wayland (zwlr_data_control_manager_v1), and Windows from a single API.

wallguard/Cargo.toml:

# Remove:
copypasta = "0.10.2"

# Add:
arboard = { version = "3", features = ["wayland-data-control"] }

messages.rs:

// Replace import:
use copypasta::{ClipboardContext, ClipboardProvider};
// With:
use arboard::Clipboard;

// Replace field type:
clctx: Option<Arc<Mutex<Clipboard>>>,

// Non-fatal init:
let clctx = match Clipboard::new() {
    Ok(ctx) => Some(Arc::new(Mutex::new(ctx))),
    Err(e) => {
        log::warn!("Clipboard unavailable ({}); paste sync disabled", e);
        None
    }
};

// Skip silently when clipboard is None:
async fn on_clipboard_message(&self, message: ClipboardMessage) -> Result<(), Error> {
    let Some(clctx) = &self.clctx else { return Ok(()); };
    clctx.lock().await.set_text(message.content).handle_err(location!())
}

---

Packaging changes

Debian — packages/debian/postinst (new file, mode 0755)

#!/bin/sh
set -e
case "$1" in
    configure)
        if command -v setcap > /dev/null 2>&1; then
            setcap cap_net_raw,cap_net_admin+eip /usr/local/bin/wallguard
        else
            echo "WARNING: setcap not found; wallguard will require root or manual setcap." >&2
        fi
        ;;
esac

Add libcap2-bin to Depends in control.tpl — it provides setcap and is present on all Debian/Ubuntu installs.

RPM — packages/rpm/wallguard.spec.tpl

Requires: libpcap, libcap

%post
if command -v setcap > /dev/null 2>&1; then
    setcap cap_net_raw,cap_net_admin+eip /usr/local/bin/wallguard
fi

Systemd service file (new, installed by both packages)

[Unit]
Description=WallGuard security agent
After=network-online.target graphical-session.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/wallguard
Restart=on-failure
RestartSec=10
# Set these for system-service deployments:
# User=<session-user>
# SupplementaryGroups=input
# Environment=XDG_RUNTIME_DIR=/run/user/1000
# Environment=WAYLAND_DISPLAY=wayland-0

[Install]
WantedBy=default.target

For uinput input injection the session user must be in the input group:

sudo usermod -aG input <username>

---

macOS notes (for when screen capture is implemented)

The same session-context problem applies on macOS but through different mechanisms:

• WindowServer — owned by the GUI login session; root cannot connect. The agent must run as a LaunchAgent (per-user session daemon), not a LaunchDaemon.
• TCC Screen Recording — enforced by code-signing identity, not UID. Root does not bypass it. The user must grant permission in System Settings → Privacy & Security → Screen Recording on first run.

The correct implementation target is CGDisplayCreateImage() via the core-graphics crate (available on macOS 10.6+), added under #[cfg(target_os = "macos")] in create_capturer().

---

Capability matrix after this work

Platform	Screen capture	Input injection	Clipboard
Linux / X11 (session user + setcap)	✅ x11rb	✅ Enigo	✅ arboard
Linux / Wayland, KDE/sway/hyprland (session user + setcap)	✅ wlr-screencopy	✅ uinput (input group)	✅ arboard
Linux / Wayland, GNOME/Mutter	❌ protocol not implemented	✅ uinput	✅ arboard
macOS	❌ not yet implemented	❓ not tested	❓ not tested
Windows (Administrator)	✅ GDI	✅ Enigo	✅ arboard
FreeBSD	✅ X11	✅ Enigo	✅ arboard