Wayland Auto-Type with XDG Desktop Portals

[hifi]

This is a major rewrite of #10905 with emphasis on error handling and usability. The original PR did not have any way to bind the global trigger.

There are definitely still shortcomings but the intention is to keep hammering this until it can be merged and keep building on it to improve the experience.

Features implemented:

• configuring global trigger with the system global shortcuts portal provider
• show configured global trigger
• reconfigure global trigger from KeePassXC if supported by portal
• keep remote desktop connection or reconnect every time (default reconnect)
• persist remote desktop connection restore token in memory or in local config (default in memory)
• gracefully handles external termination of remote desktop connection
• gracefully timeout if user doesn't answer to remote desktop consent
• libxkbcommon keysym mapping for as full Unicode support as possible
• prevent typing into KeePassXC main window with in-app focus detection
• builds without WITH_X11 to have Wayland-only build without direct X11 dependencies

Fixes #2281
Closes #10905

Screenshots

New configuration options if the plugin is loaded:

Initial configuration dialog on KDE:

Testing strategy

• on KDE Plasma 6.3 (Debian trixie) everything works except reconfiguring from KeePassXC (shortcuts portal v1 only)
• on KDE Plasma 6.6 (Debian forky) all above and reconfiguring from KeePassXC (shorcuts portal v2 supported)
• on GNOME 48 (Debian trixie) initial binding works, changing shortcut from GNOME settings fails silently until session restart (GNOME bug)
• on GNOME 50 (Debian forky) it works pretty much like on KDE Plasma 6.3 but I have a bug that the configuration dialog is blank, not related to the PR itself, it works just fine after that, including rebinding

There are multiple quirks in place for global shortcuts, mostly because of GNOME, but if all stars align with fresh enough KDE everything works like one would expect.

Type of change

• ✅ New feature (change that adds functionality)

[Copilot]

Pull request overview

This PR introduces a Wayland Auto-Type backend using XDG Desktop Portals (RemoteDesktop + GlobalShortcuts), adds UI support to configure portal-managed global shortcuts, and persists the RemoteDesktop restore token via the app config.

Changes:

• Add a new Wayland Auto-Type platform plugin that types via the XDG RemoteDesktop portal and stores a restore token for session persistence.
• Integrate the XDG GlobalShortcuts portal on Unix (NixUtils) and expose a “Configure…” button in settings when shortcuts are managed externally.
• Add DBus interface XMLs + CMake/vcpkg plumbing for portal interfaces and the xkbcommon dependency.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
vcpkg.json	Adds a new Linux/FreeBSD dependency for xkbcommon.
src/gui/osutils/OSUtilsBase.h	Adds hooks for “external shortcut configuration” and a slot to open a configurator UI.
src/gui/osutils/nixutils/NixUtils.h	Declares portal request helper + configurator-related overrides/state.
src/gui/osutils/nixutils/NixUtils.cpp	Implements GlobalShortcuts portal session creation, binding UI, and Wayland/X11 shortcut behavior changes.
src/gui/osutils/nixutils/dbus/org.freedesktop.portal.Session.xml	Adds DBus XML for the portal Session interface (Qt DBus codegen).
src/gui/osutils/nixutils/dbus/org.freedesktop.portal.Request.xml	Adds DBus XML for the portal Request interface (Qt DBus codegen).
src/gui/osutils/nixutils/dbus/org.freedesktop.portal.RemoteDesktop.xml	Adds DBus XML for the portal RemoteDesktop interface (Qt DBus codegen).
src/gui/osutils/nixutils/dbus/org.freedesktop.portal.GlobalShortcuts.xml	Adds DBus XML for the portal GlobalShortcuts interface (Qt DBus codegen).
src/gui/ApplicationSettingsWidgetGeneral.ui	Adds a “Configure…” button under Auto-Type shortcut settings.
src/gui/ApplicationSettingsWidget.cpp	Toggles shortcut widget vs. portal configure button based on OSUtils capability.
src/core/Config.h	Adds a new config key for the desktop portal restore token.
src/core/Config.cpp	Registers the restore token config directive (Local storage).
src/CMakeLists.txt	Adds Qt DBus interface code generation for the portal XMLs.
src/autotype/wayland/CMakeLists.txt	Introduces the Wayland Auto-Type plugin build target and links to xkbcommon/DBus.
src/autotype/wayland/AutoTypeWayland.h	Declares the Wayland Auto-Type platform plugin + executor.
src/autotype/wayland/AutoTypeWayland.cpp	Implements RemoteDesktop portal session lifecycle and key injection via NotifyKeyboardKeysym.
src/autotype/CMakeLists.txt	Adds the Wayland plugin subdirectory (currently under WITH_X11).
src/autotype/AutoType.cpp	Adds a guard for null plugin and queues matchActivated handling.
cmake/FindXkbcommon.cmake	Adds a custom find-module for xkbcommon (pkg-config or manual fallback).

Comments suppressed due to low confidence (1)

src/autotype/wayland/AutoTypeWayland.cpp:171

• On Start() failure you set m_error and unlock, but you keep m_remoteDesktopSession alive. This blocks retries because tryStartSession() will treat the session as already started. Please close/reset the session on error to allow recovery and avoid using a half-initialized session object.

    auto reply = s_remoteDesktopInterface->Start(QDBusObjectPath(m_remoteDesktopSession->path()),
                                                 "",
                                                 {
                                                     {QLatin1String("handle_token"), handleToken},
                                                 });
    reply.waitForFinished();
    if (reply.isError()) {
        m_error = "Failed to start remote desktop session: " + reply.error().message();
        m_startLock.unlock();
    }

[Zahrun]

I tested this branch on Tuxedo OS, which is currently on KDE Plasma 6.5.2.
It works perfectly, the configuration in the settings allowed me to set a Global Auto-Type shortcut. Using the shortcut the first time requests for control permission, then shows auto type dialog which allows me to search for an entry and have it typed. The token is kept for the following auto type requests. Even after closing and re-opening keepass, it still gets the control permission saved.
Thank you for the good work!

My only comment is that the three first options in the "Auto-Type" settings tab might be confusing for some people, since on Wayland there is no matching windows.

[minortex]

Some problems occured when I use the fcitx5 input method.
This affects CJK users first, but the same class of issue may affect other IMEs, non-US layouts, or virtual keyboard setups. It will be great if fixes can be done. Thanks for your great work.

Wrong alphabet inputted on fcitx5 activated

J5KZUJ`z24dk@VdLo%S_r # original password
j%kZUJ~z24dk2VDlO5S_R # keepassxc inputted

Confirmed that keyboard-us layout is selected. It looks like fcitx5 receives the virtual keyboard events and corrupts or delays modifier state. Besides, after the auto-type operation, my shift key is pressed but not released properly.

---

I tried Fcitx5 wayland launcher or Fcitx5 in Virtual Keyboard of KDE settings, neither works.

When I switch to none, it works, so seem to be a IM compatibility problem.

Input method state can't be changed

When I use previous version of autoinput (using dbus-send script to trigger, with some modification with codex), I can use this script to manually switch to keyboard-us:

fcitx5-remote -s keyboard-us && dbus-send --session --type=method_call --dest=org.keepassxc.KeePassXC.MainWindow /keepassxc org.keepassxc.KeePassXC.MainWindow.requestGlobalAutoType

But after global shortcut introduced, there is no way to inject my switch logic, so when I'm on rime, keepassxc use my fcitx to input "Chinese".

Possible fixes / workarounds

1. Provide an optional pre-Auto-Type command/hook, or keep a DBus-triggered global Auto-Type entry point, so users can switch IM state before Auto-Type starts.
2. Consider a keycode-based injection mode for Wayland RemoteDesktop instead of NotifyKeyboardKeysym, or at least make it configurable. The current keysym-based path appears to interact badly with fcitx5's modifier handling.

[hifi]

@minortex Thank you for testing with a custom input method. Since KeePassXC sends keysyms that are directly derived with libxkbcommon from the unicode characters I believe the wrong conversion happens on the other side as KeePassXC does nothing regarding keyboard layouts or input methods and shouldn't be doing.

You should try a dbus monitor command to see what's being sent exactly and if it matches the symbols of your password then you should file a bug against the desktop portal for converting them incorrectly with your input method. I'd be interested to hear if the symbols that KeePassXC sends are correct or not because that would confirm my hypothesis.

[hifi]

@Zahrun Thanks for the comments. I've now addressed this by hiding them if the plugin doesn't support window management.

[KylerianHD]

First of all, a huge thank you for this PR.

I tested it on Arch Linux and the latest KDE Plasma, and it works flawlessly. All options work as expected and as they should. This was one of the more annoying features to be missing on Wayland, and to see that you made it work while cleaning up, plus extending the original PR (#10905), is seriously amazing.

Thanks again and have a great day!

[minortex]

@hifi Oh, the classic Linux desktop rabbit hole! 😂

Since keepassxc is emitting perfect keysyms, this is indeed an upstream/downstream issue with how the compositor and the Input Method Framework handle virtual keysym re-interpretation. If I report this to fcitx5 or kwin, it will likely end up in an endless game of pass-the-parcel regarding who owns the virtual keyboard timing.

To make keepassxc's Wayland implementation genuinely bulletproof for CJK and non-US layout users without waiting years for upstream portal fixes, having a keycode-based injection toggle or a pre/post auto-type script hook inside keepassxc would be a lifesaver.

It gives users the exact escape hatch they need when their desktop environment's IM framework decides to mess up the modifier states.

[droidmonkey]

Who receives and processes the dbus call? I suspect that is fcitx5. That is who gets the ticket to fix their implementation. Offering complex workarounds on our initial implementation is not the correct way to handle this. We already are working around awful handling of global shortcut setting across gnome versions.

[minortex]

@droidmonkey Totally understand it's a pity to resolve different quirks on DEs.

However, to isolate the issue, I tested three entirely different virtual keyboard backends in KDE system settings:

1. fcitx5 -> bug recurs.
2. ibus -> bug recurs.
3. plasma virtual keyboard (KDE's native osk) -> bug recurs.

It will be easy for you to verify the bug since it is installed by default. Even under a standard US layout, you will see the modifier state corrupting.

Since the same modifier/Shift corruption happens across all three frameworks, this is definitively a KDE/KWin/Portal bug, not an fcitx5 issue.

Will report this to KDE, but please consider the impact on touchscreen users. Thanks for your help!

[hifi]

@minortex While I do understand your issue is very practical I don't think it would be worth the trouble adding sending keycodes when the only logical way to send characters of a password is with keysyms as you'd need to configure a virtual keymap within KeePassXC for it to convert characters to modifiers and keycodes which is the complete opposite of what it should be doing because it has no context where the output is going to. This should be done by the compositor which knows what layout is currently active and if there's something to do with input methods it must be a dance between them to figure that out.

There are a few ways for you to go forward without doing this within KeePassXC:

1. On KDE specifically, you can invoke any shortcut against its own dbus service and keep your script, this depends on the correct .desktop file being used: dbus-send --session --print-reply --dest=org.kde.kglobalaccel /component/KeePassXC org.kde.kglobalaccel.Component.invokeShortcut string:"autotype"
2. Have a secondary binding to toggle between layouts
3. Write a proxy implementation for the Global Shortcuts portal that allows command line activation of a shortcut, likely unnecessary if you're on KDE
4. Write a proxy implementation for the Remote Desktop portal that converts keysyms to keycodes in a way that prevents the conversion issue from happening, essentially what you want KeePassXC to be doing but external

These proxies could even be written fairly quickly with an LLM in something like python and you'd have a temporary fix for your whole system. The XDG Desktop Portal thing is quite flexible so you should be able to just configure your proxy as the backend and make your proxy directly call the real implementation. This of course assumes some programming knowledge but just throwing it out there.

Also do note that KDE got a fix for keysym mishandling for this very reason last year in Plasma 6.5 so if you're on any older release it's known to be buggy. I'm currently on Debian trixie which has the bug but I only use a single layout so it doesn't affect me.

[minortex]

All right, I ask llm to craft a script to resolve this problem.

Here is the implemenetation strategy:

1. Disable Kwin's virtual board temporaily, avoiding interrupt auto type process.
2. Trigger auto type.
3. use dbus-monitor to analyzing the input process, and raise a signal when typing completed.
4. re-enable virtual keyboard and refresh window status (some strange bug make it unable to use IME until manually switch window).

Hope this helps anyone else stuck in wayland and cjk limbo.

My issue is fully resolved now, huge thanks to everyone for the helpful suggestions and insights.

And the script:

#!/bin/bash

# ==============================================================================
# KeePassXC Wayland Auto-Type Fix for KDE Plasma 6 & Fcitx 5
# ==============================================================================
# This script eliminates character-dropping, sequence-scrambling, and casing bugs
# caused by race conditions between KWin's virtual keyboard pipeline (text-input)
# and KeePassXC's simulated keysyms under Wayland.
#
# Added Watchdog: Prevents the script from hanging indefinitely and freezing the
# IME input state if Auto-Type is cancelled or KeePassXC is locked.
# ==============================================================================

# 1. Temporarily unbind the IME pipeline to restore pure hardware-level input timing
qdbus org.kde.KWin /VirtualKeyboard org.kde.kwin.VirtualKeyboard.enabled false
sleep 0.05

# 2. Trigger KeePassXC Global Auto-Type via KDE 6's precise global shortcut pathway
qdbus org.kde.kglobalaccel /component/org_keepassxc_KeePassXC \
  org.kde.kglobalaccel.Component.invokeShortcut "autotype"

# 3. Dynamic Traffic Monitor (Spawned in background)
# Wait for typing to begin, then track simulated keystrokes.
# It blocks until it detects a 0.3-second "silence" (stream timeout),
# which dynamically adapts to passwords of any length.
(
  while read -r line; do
    while read -t 0.3 -r next_line; do
      true
    done
    break
  done < <(dbus-monitor --session "type='method_call',interface='org.freedesktop.portal.RemoteDesktop',member='NotifyKeyboardKeysym'" | grep --line-buffered "NotifyKeyboardKeysym")
) &
MONITOR_PID=$!

# 4. Fail-Safe Watchdog (Spawned in background)
# If typing doesn't finish within 15 seconds (e.g., user cancels or database is locked),
# it forcibly terminates the monitor to prevent freezing the system's input method.
(
  sleep 15
  if kill -0 $MONITOR_PID 2>/dev/null; then
    echo "[KeePassXC Fix] Auto-Type timed out or cancelled. Activating fail-safe." >&2
    kill $MONITOR_PID 2>/dev/null
  fi
) &
WATCHDOG_PID=$!

# Wait for the monitor to finish (either normally or killed by the watchdog)
wait $MONITOR_PID 2>/dev/null

# 5. Re-enable KWin's virtual keyboard component now that typing is finished
qdbus org.kde.KWin /VirtualKeyboard org.kde.kwin.VirtualKeyboard.enabled true
sleep 0.1

# 6. Fix Lost Input Context (KDE 6 Wayland Ghost Bug)
# Toggling the component destroys the Wayland socket connection. To prevent the active
# window from being stuck in "English-only" mode until manually clicked, we briefly
# trigger a 20ms "Show Desktop" cycle. This forces KWin to refresh the focus state
# and seamlessly rebuilds the text-input context for the active input field.
qdbus org.kde.KWin /KWin org.kde.KWin.showDesktop true
sleep 0.02
qdbus org.kde.KWin /KWin org.kde.KWin.showDesktop false

# ==============================================================================
# 7. Housekeeping: Process Group Clean-up
# ==============================================================================
# Clear exit traps to prevent potential infinite loops
trap - EXIT

# Kill the watchdog timer if it's still running
kill $WATCHDOG_PID 2>/dev/null || true

# Nuclear Option: Terminate the entire process group (-$$)
# This instantly wipes out any remaining sub-processes (like dbus-monitor or grep)
# generated by this script, ensuring no zombie or orphan processes are left behind.
kill -- -$$ 2>/dev/null || true

Disable the original keybinding, and simply bind this script to KDE's shortcuts and it will work.

[droidmonkey]

@minortex for our awareness, what version of plasma are you running?

[minortex]

@droidmonkey

Operating System: Arch Linux 
KDE Plasma Version: 6.6.5
KDE Frameworks Version: 6.26.0
Qt Version: 6.11.1
Kernel Version: 7.0.9-zen1-1-zen (64-bit)
Graphics Platform: Wayland
Processors: 8 × Intel® Core™ i5-10210U CPU @ 1.60GHz
Memory: 16 GiB of RAM (15.4 GiB usable)
Graphics Processor: Intel® UHD Graphics
Manufacturer: Google
Product Name: Kled
System Version: rev7

[michaelk83]

note that KDE got a fix for keysym mishandling for this very reason last year in Plasma 6.5

The specific MRs were: xdg-desktop-portal-kde/!342, plasma-wayland-protocols/!92, and kwin/!6992, for KDE bug 489021.

@minortex If you post a followup bug to KDE, please link to it here.

[droidmonkey]

Just minor comments, code is clean and readable, great work!

[minortex]

note that KDE got a fix for keysym mishandling for this very reason last year in Plasma 6.5

The specific MRs were: xdg-desktop-portal-kde/!342, plasma-wayland-protocols/!92, and kwin/!6992, for KDE bug 489021.

@minortex If you post a followup bug to KDE, please link to it here.

I looked closely into the diffs of those MRs, and while they indeed removed the hardcoded KEY_LEFTSHIFT injection from portal, then re-introduced the exact same KEY_LEFTSHIFT automated injection logic inside KWin's backend.

In the MRs you mentioned, It solved the problem that European/American keyboard with different key places. But they don't take virtual keyboard into consideration.

Therefore, my problem is not related to that. It's necessary to explain how the IME works:

1. user types raw alphanumeric keys to form an input sequence representing the pronunciation(e.g. Pinyin)
2. the IME intercepts these keys and buffers them into a pre-edit string.
3. the IME dynamically maps the input sequence to matching ideographs and displays them in a floating candidate window.
4. the user types a number key to select the intended ideograph from the candidates.
5. finally the IME commits the selected text, sending the actual ideographs into the active text field.

In KDE, simulating keyboard input will conflict with IME, because IME will process the original key input, which causes the problem.

I thought it's never be a good idea to simulate the keyboard press event as the input event, causing endless bugs.

Look at windows, they treats the input as unicode so auto type works well, KeePassXC doesn't face such problem.

This PR is going to be merged and it's not the KeePassXC team's responsibility, the only real solution is to request KDE's team to implement a better accessibility framework, and I won't clutter this thread any further.

[hifi]

@droidmonkey I added support for showing the bound trigger from the desktop and integrated it back into the shortcut widget instead of having a separate button. Focus with the field works correctly and clicking or hitting return will try to open the (re)configuration window of the desktop. Left it as a fixup for easier re-reviewing.

This should be as good as it gets on KDE now. On GNOME you do see the binding and the field reacts to it live so the only missing feature on GNOME is reconfiguration from within KeePassXC.

[hifi]

If someone wants to test this on something else than KDE or GNOME, I whipped up a minimal portal in python that can bind global shortcuts on any compositor and implements enough remote desktop on most: https://github.com/hifi/xdg-desktop-portal-pyrtal

I've tested this on labwc and it works fine for me so expecting it to work on any wlroots based compositor and Hyprland.

[mavaa]

After some finicking, I managed to test this on sway, and it works 🎉

I made it harder for myself by trying to use uv and setting up pyrtal as (cd $HOME/src/tools/xdg-desktop-portal-pyrtal/ && uv run python -m pyrtal "$@"), but as Claude taught me, I had to set it up using my system native python rather than a clang compiled one that it apparently downloads by default(?), or os.memfd_create would be unavailable.

I only have a small issue, which I'm not sure if is related to uv, but the keepassxc fork registers itself as '', so that I have to use pyrtal trigger '' autotype rather than pyrtal trigger org.keepassxc.KeePassXC autotype. I tried asking about this, and got:

Found it. CreateSession in NixUtils.cpp:583-586 never passes an app_id field — it only sends
session_handle_token and handle_token . The app_id is supposed to come from the portal caller's D-Bus
sender identity (which xdg-desktop-portal normally injects when the app is registered as a Flatpak), but
since KeePassXC runs natively it doesn't have one, so the portal receives an empty string.
This is worth mentioning to the contributor — to fix the pyrtal-side trigger UX, pyrtal could fall back
to matching by session path rather than app_id , or KeePassXC could explicitly pass app_id in the
options map (though the spec doesn't define that). The real fix is that pyrtal trigger should accept a
session token or just trigger all active sessions, since empty app_id is expected for non-Flatpak apps.

I have no idea if this is correct information, but I would very much like to avoid having to run flatpak to get autotype. (Not trying to hate on flatpak, I just prefer to run things natively).

[hifi]

@mavaa Thanks for testing! I believe there's a bug that races the registration of the DBus service without an app_id which breaks on some setups. I'm looking into it next as I've also hit this on some desktops but not all so it might be related to the version of Qt6 changing some initialization behavior but since I have a repro I should be able to fix it if it's indeed something on our side.

[hifi]

@mavaa Pushed a fix, let me know if it worked!

It fixed it in the environments where I had trouble. One dependency is that you need to have a .desktop file installed (in ~/.local/share/applications is enough) that can correctly launch your KeePassXC build and has the same name that KeePassXC registers (org.keepassxc.KeePassXC).

[hifi]

Kept testing on labwc and I still got an empty app id, it was a different issue but not related to KeePassXC itself.

The portal frontend has strict checking on some stuff which can be satisfied on my system with:

$ systemd-run --user --unit="app-foo-keepassxc" ~/git/keepassxc/build/src/keepassxc

[mavaa]

(I forgot to send this, and see that you've figured out something similar now, but sending it anyways)

I managed to get it working after even more hassle, but I think it's an issue with my setup rather than yours. I (Claude) figured out that if I run this, it works perfectly due to some regex shenanigans:

systemd-run --user --scope \                           
     --unit "app-org.keepassxc.KeePassXC-$$" \
     /path/to/my/srcc/keepassxc/build/src/keepassxc

But i use sway-launcher-desktop, which apparently "only" execs what's on the "Exec=" line from the .desktop file directly.

[phoerious]

Good enough. I've tested it and it works quite well, good job! Let's fix any remaining issues after this has been merged.

[droidmonkey]

Agree this is ready to merge once the last comment is resolved.