Linux Wayland Environments (Non-X11) Are Unable to Type. Only a user initiated clipboard paste works

[tobor88]

Known Issues

This document tracks known limitations and behavioral quirks in NovaKey that are
intentional (for now) but open for improvement. If you want to
contribute, this is a good place to start.

---

1. Linux Wayland: No Keystroke Injection (Clipboard-Only)

Status: Known limitation
Scope: linux, Wayland sessions (XDG_SESSION_TYPE=wayland)
Impact: Password is copied to clipboard, but no characters are typed into the focused window.

Symptoms

On a Wayland session:

• NovaKey logs show successful decryption and an attempt to inject:

  [linux] InjectPasswordToFocusedControl called; len=23 DISPLAY=:0 XDG_SESSION_TYPE=wayland
  [linux] async password copied to clipboard (wayland; manual paste required)
  InjectPasswordToFocusedControl error: wayland session: keystroke injection not implemented; clipboard only
  

• The password does appear in the clipboard (you can paste it manually with Ctrl+V).
• Nothing is auto-typed into the browser address bar, terminal, or text editor.

This is by design: NovaKey currently does not attempt keystroke injection on Wayland.

Why This Happens

NovaKey’s current Linux injector is based on:

• xdotool for simulated keypresses.
• xclip for clipboard.

These are X11 / Xwayland tools. On a native Wayland session:

• xdotool cannot see or control Wayland-native windows.

• Any attempt to “type” would be unreliable or silently fail.

• Instead of pretending it worked, NovaKey:

  • Copies the password into the clipboard (best effort).
  • Returns a clear error saying Wayland keystroke injection is not implemented.

Current Behavior (Runtime Logic)

At runtime, NovaKey checks XDG_SESSION_TYPE:

• If XDG_SESSION_TYPE=wayland:

  • Start a goroutine that calls xclip to set the clipboard.
  • Log a message indicating that only clipboard is supported.
  • Return an error:
    wayland session: keystroke injection not implemented; clipboard only

• Otherwise (X11 / Xwayland / unset):

  • Use the original, working logic:

    • Async clipboard via xclip.
    • Synchronous typing via xdotool type.

This keeps behavior 100% correct and explicit, instead of silently failing.

Workarounds

Until proper Wayland support is implemented:

1. Use X11 / Xorg Session (Preferred for now)
   Log out and choose an Xorg session instead of Wayland (GNOME, KDE, etc. usually offer both).

2. Run Target Apps Under Xwayland (Where Possible)
   Some applications can be forced to run under Xwayland, for example:

   MOZ_ENABLE_WAYLAND=0 firefox

   In that case, xdotool may work again even if the session is Wayland, because the app is running inside an Xwayland bridge.

3. Clipboard-Only Mode
   Use NovaKey to populate the clipboard and paste manually (Ctrl+V).

   This is less ideal but still avoids typing the password yourself.

---

2. Potential Future Fix: Proper Wayland Injection

Good first contribution: Design and implement a Wayland-native injector that preserves NovaKey’s security model.

Design Goals

• Continue using the existing high-level API:

  func InjectPasswordToFocusedControl(password string) error

• Keep the existing X11 / Xwayland behavior intact.

• Add a Wayland-specific path that:

  • Works on major compositors (GNOME, KDE Plasma, Sway, etc.) where feasible, or
  • At least works on one major compositor as a starting point (sway/Hyprland, etc.).

• Explicitly document any extra dependencies or permissions (e.g. uinput, root, systemd service).

Possible Approaches

Here are some directions that could save you time:

1. ydotool (uinput-based tool)

   • Pros:

     • Works at the Linux input layer via uinput.
     • Can often inject keys even on Wayland if the compositor allows it.

   • Cons:

     • Usually requires:

       • ydotoold daemon running.
       • Root or special group permissions to access /dev/uinput.

     • Security model and permissions need to be clearly documented.

   A potential implementation would be:

   • Detect Wayland.

   • If ydotool is available and configured:

     • Use ydotool type "..." as the Wayland typing backend.

   • Otherwise:

     • Fall back to clipboard-only + explicit error (current behavior).

2. Compositor-Specific Tools (e.g. wtype on wlroots/sway)

   • Tools like wtype can send key events to wlroots-based compositors.

   • This path would likely be best-effort and compositor-specific, so design it as:

     • Optional.
     • Controlled via config or compile-time tags.
     • Clearly documented as “supported on sway/Hyprland/etc, not GNOME/KDE”.

3. Wayland Virtual Keyboard Protocol (wlr-virtual-keyboard / similar)

   • More “native” and potentially more secure.

   • But requires deeper integration with specific compositors.

   • Likely a larger project and might need:

     • A small helper daemon speaking the Wayland protocol.
     • Additional runtime dependencies.

Suggested Architecture for Contributors

To avoid a messy if jungle, consider:

type KeyInjector interface {
    Inject(password string) error
}

func newLinuxInjector() KeyInjector {
    session := os.Getenv("XDG_SESSION_TYPE")
    switch session {
    case "wayland":
        // Future: return a Wayland-capable injector (ydotool, wtype, etc.)
        return &waylandClipboardOnlyInjector{}
    default:
        // Current X11/Xwayland injector (xdotool + xclip)
        return &x11Injector{}
    }
}

Then InjectPasswordToFocusedControl just delegates to the chosen injector.

Things to Document in a PR

If you decide to implement Wayland injection, please include:

• New dependencies required
  Example: “Requires ydotool and ydotoold with access to /dev/uinput.”

• Configuration knobs
  E.g., server_config.json flag to enable/disable Wayland typing, or select backend: xdotool | ydotool | wtype.

• Security considerations

  • Impact of granting /dev/uinput access.
  • Any need for elevated privileges or special groups.

• Tested environments

  • Distro, compositor, and session type.
  • Example: “Fedora 41, GNOME on Wayland, ydotool 1.0.0”.

---

3. How to Help

If you want to tackle this:

1. Open a GitHub Issue titled something like
   “Wayland keystroke injection backend (ydotool / wtype / virtual keyboard)”.

2. Sketch the approach you plan to take.

3. Reference this file (KNOWN_ISSUES.md) in your issue/PR.

4. Submit a PR with:

   • Minimal, well-scoped changes.
   • Clear documentation updates (README + this file).
   • Logging that makes failure modes obvious.

We’ll review PRs with a strong preference for:

• Clear, explicit behavior over “magic that sometimes works”.
• Minimal extra privilege / attack surface.
• Good documentation for users and packagers.

---

If you’ve hit a Wayland limitation and want to add more details (distro, compositor, logs),
feel free to open an issue and link to the relevant section above.