Skip to main content

portal service channel

The installed Ubuntu GNOME portal backend requires Mutter's org.gnome.Mutter.ServiceChannel interface before it creates a native GTK display. Its OpenWaylandServiceConnection method takes portal service type 1 and returns a Unix file descriptor ((u) -> h). The backend opens this connection before acquiring its well-known portal bus name. GNOME 51 also requests typed connections for Nautilus as the file chooser (type 2) and the control-center global-shortcuts helper (type 3).

The genuine GTK run for capture PR #252 at e4bea38e2a2522e3555a24a285bbf81b180f6a14 failed G-PORTAL-CONSENT on 2026-10-04. The installed backend logged “Non-compatible display server, exposing settings only”; the frontend reported a missing ScreenCast interface and returned CreateSession response 2. This occurred before a picker existed. The same run passed native no-XWayland startup, server/XIM restart, long-folder viewport and held edge paging, native IBus composition/candidates, and genuine GTK3 XIM.

Tuna Desktop provides the requested ordinary Wayland connection only to a same-user D-Bus caller whose PID resolves to the installed, root-owned, non-writable executable for the requested type. Type 1 accepts the GNOME portal backend, type 2 accepts /usr/bin/nautilus, and type 3 accepts gnome-control-center-global-shortcuts-provider in /usr/libexec or /usr/lib. A binary admitted for one type is not admitted for another. This bootstrap cannot require the portal's not-yet-acquired well-known name. Connections use ordinary client permissions, not the IME bridge or shell role. Typed providers retain one live typed connection per unique caller. Ordinary clients may open multiple displays; both methods share a maximum of 32 live connections, and disconnected connections free their slots. Unsupported service types are rejected.

Opening a display is not capture admission. The existing ScreenCast methods still require the current unique portal owner or supervised shell, enforce session ownership, and deny or revoke capture while locked. A backend may initialize its ordinary display while locked, just as ordinary Wayland clients may connect, without gaining a capture grant.

The real security client checks denial for all three types from an untrusted caller, including forged portal, Nautilus and global-shortcuts-provider service names. The full current-head GNOME picker Cancel/Share, frame consumption, owner Close, lock and disconnect proofs remain required before acceptance.

Upstream contracts: Mutter 46 ServiceChannel, GNOME portal 46 native display initialization.

The subsequent Ubuntu GTK run at eb572636 reached the real ScreenCast interface and returned CreateSession response 0, confirming native bootstrap. SelectSources then failed with “Unavailable cursor mode 1”. The proof had launched the backend and frontend together; GNOME 46 publishes ScreenCast capabilities asynchronously, while the frontend snapshots those properties on initialization. The driver now waits for actual backend properties before launching the frontend, then requires frontend properties too: version at least 2, monitor source support and hidden-cursor support. Each call has a 500 ms timeout and the overall wait is bounded to 30 seconds, without D-Bus auto-start. The original cursor request and picker/security assertions stay unchanged.

The corrected ordering passed the actual GNOME 51 reference journey with the retained eb572636 compositor and shell binaries on 2026-10-04: Cancel, Share, frame consumption, Close, client/backend disconnect, active-stream lock revocation and locked denial. Backend and frontend readiness evidence both recorded version 5, source types 7 and cursor modes 7. This separate control does not replace the pending full current-head Ubuntu GTK and package checks.

Remaining GNOME interoperability qualification​

Typed display admission is a prerequisite, not proof that GNOME's file picker or global shortcuts work end to end. Issue #395 remains open for genuine GNOME provider startup and operations on the shipped VM, file-picker Open/Save and sandbox grants, shortcut consent/rebinding/activation, and lock/capture negative checks. The mutter_x11_interop dialog-parenting protocol remains a separate contract in #404; neither display method implements it. Current acceptance evidence must identify the installed GNOME versions and actual provider executables.

Source contracts: Mutter 51 typed service interface, Nautilus 51 file-chooser initialization, and GNOME control-center provider installation.

Ordinary options-based display connections​

OpenWaylandConnection(a{sv}) -> h accepts an authenticated same-user process with ordinary Wayland client permissions. It is available while locked, as ordinary display connections are, and does not confer a trusted provider, capture, virtual-keyboard or session-lock role. Its optional string window-tag becomes window metadata for this connection; an explicit xdg-toplevel tag overrides it, and other clients inherit no tag. Unknown options and incorrectly typed tags are ignored as in Mutter 51. Tags exceeding 1024 UTF-8 bytes are rejected with InvalidArgs to bound retained metadata.

The options and typed methods share the live connection budget, while an ordinary connection does not consume the caller's single typed-provider slot. The real untrusted D-Bus proof opens two tagged ordinary connections, completes actual wl_display.sync on both, then still requires typed-provider and capture denial from that same caller. The existing GTK and GNOME 51 portal reference drivers run this proof both unlocked and locked. Unit coverage separately drives socket sync, exhaustion, disconnect slot reuse, real xdg windows, inherited tags and explicit tag overrides. Execution results must be retained from the current head before qualification; this description does not claim a passing end-to-end Nautilus Open/Save journey.

Standalone running applications​

GNOME's running-app list requires at least one window without a transient parent. Tuna Desktop snapshots that eligibility from actual Wayland role relationships (including imported foreign parents) or managed X11 parent metadata, rather than treating a supplied application ID as evidence of a standalone window. A transient dialog's focus still counts for its application when that application also has a standalone window; inactive applications omit active-on-seats, matching GNOME 51. Window selection itself continues to include dialogs.

Candidate regression coverage drives real same-client parent assignment/detachment and cross-client export/import/withdrawal, then checks the window manager's eligibility and removal. App-list tests cover transient-only providers, focused dialogs belonging to standalone apps and detached dialogs. Current-head execution and admitted portal/shipped-image qualification remain required. Authenticated sandbox identity, actual auxiliary-X11 type transitions through an admitted portal and full GNOME app selection in #410 remain unqualified.

Eligible windows in the GNOME picker​

GetWindows filters the shared snapshot using live window-role metadata. Native xdg toplevels (including transient dialogs and foreign-parented file pickers) remain eligible. Managed X11 windows with Normal, Dialog or Utility types remain eligible; a missing type defaults to Normal. X11 desktop, dock, combo, drag-and-drop, notification, menu, popup/dropdown menu, splash, toolbar and tooltip types are excluded. The pinned Smithay patch recognizes all fourteen EWMH window types, including four auxiliary types it previously treated as unrecognized. Override-redirect windows are already refused by the XWM map path and the picker eligibility check also rejects them. Modal X11 dialogs retain the Dialog type. Property changes are read for each publication, so an eligibility change updates the snapshot and emits WindowsChanged.

This window filter is independent of GetRunningApplications: the app list still uses standalone-window relationships and includes focus from all of an eligible app's windows. Neither client-supplied window types nor this enumeration grant capture/provider authority. Tests cover the GNOME type matrix, independent app-focus aggregation, real native transient/foreign-parent relationships and unmapping. The GTK proof changes all fourteen real EWMH types on its mapped X11 client, retains each compositor policy result and restores the absent-type default; execution of this new proof is pending. Admitted-portal X11 type-change selection, sandbox IDs and shipped-image VM qualification remain required; this source change does not close #410.

Reference: GNOME Shell 51 Introspect eligibility.

Genuine GNOME 51 file-picker journey​

The GNOME 51 backend implements FileChooser by delegating to org.gnome.Nautilus; the existing gnome portal preference selects that path. The isolated portal reference image now runs the whole session as ordinary UID 1000 with genuine GNOME 51 Nautilus installed and exercises OpenFile and SaveFile, each with Cancel and acceptance. It records real portal responses, the Nautilus unique owner/PID/installed executable, actual accessible dialog contents/screenshots, and the chosen file's bytes and hash. Open clicks the actual uniquely named fixture file cell once using its accessibility bounds and compositor focus, requires the exact file cell to be selected, and invokes the accept action; Save chooses a nonexistent destination and the requesting application writes and reads its content. Cancel must return no URI and must not create a Save destination. Native-display fallback warnings fail the journey; the separately tracked missing X11 interop warning is retained.

This reference runs a packaged candidate against GNOME 51 in a nested Wayland session. It does not itself establish shipped-image VM file-picker qualification, Flatpak document grants, parent-dialog focus behavior, multiple output/scales or locked file-picker operation; those remain in #395/#404. Current-head execution must pass before any Open/Save interoperability claim.

Nautilus 51 explicitly refuses root startup. The first new FileChooser run exposed this fixture limitation: Nautilus exited 95 and the frontend returned response 2 before any UI decision. The corrected image creates an ordinary fixture user and runs the complete compositor/shell/portal/Nautilus graph under that user's session bus. A root wrapper prepares and restores artifact ownership without running application operations as root. The actual UID is recorded, and original exit status and all consent/denial assertions are retained. Actual corrected-head execution remains required.

The ordinary-user run started genuine Nautilus and displayed the fixture file, but its UI driver initially waited for a nonexistent Cancel button. The retained GNOME 51 dialog exposes a header-bar Close button instead. The driver now invokes that actual accessible widget; the requesting client must still receive cancellation response 1 with no URI or new Save destination. Opening the dialog alone does not qualify Open/Save interoperability, and execution of all four decisions remains required.

Subsequent ordinary-user runs returned real OpenFile cancellation response 1 with no URI, but Ctrl+L did not expose an editable entry and the Ctrl+A driver retained an unselected fixture cell. The current driver clicks the unique actual file cell once, validates window-relative accessibility bounds against the compositor-known focused Nautilus rectangle and the nested host window, and observes fresh selection state with the GLib context pumped and AT-SPI caches cleared. It requires exactly the expected selected file, rejects a portal response before explicit acceptance, then invokes the actual accept button. Click coordinates and selected state are retained. The exact URI, file-content and stable-provider assertions remain; all corrected-head decisions must execute before qualification.

At candidate 2f7bfe9, the genuine installed Nautilus journey executed all four outcomes successfully in portal-security. Both acceptances returned the exact expected local URI and round-tripped 49 application bytes; both cancellations returned response 1 without a URI, and Save cancellation created no destination. All requests retained the same Nautilus owner, PID and installed executable. This is reference-session evidence; integrated-head gates and the broader shipped/Flatpak/parenting cases remain required.

Original service-client process identity​

A service channel creates its socketpair inside Tuna Desktop, so ordinary socket peer credentials can describe the compositor rather than the requesting application. Admission now obtains UID, PID and optional process descriptor together through the bus's GetConnectionCredentials and retains that original credential snapshot on the inserted Wayland client. The same-user, installed-provider and connection-budget checks remain separate from capture and input authorization.

The compositor's authenticated_service_client_pid API returns a numeric PID only while a bus-supplied ProcessFD pins a live original process. A missing descriptor, an exited process or a polling error yields no identity; it never substitutes the socketpair creator or opens a new descriptor from a potentially recycled PID. Older buses that omit ProcessFD can still open their ordinary display connections. The local ordinary-user bus probe returned UID/PID but no process descriptor; descriptor support in the shipping GNOME session must be checked separately.

This is groundwork for #410, not sandbox metadata publication. Directly accepted native clients, X11 identities, Flatpak/Snap identities, actual portal selection and shipped-image qualification remain required. The new tests use actual child-process descriptors and a real Wayland surface to check original identity, socketpair-creator differences and peer exit; they are awaiting CI execution. Primary contract: D-Bus GetConnectionCredentials.

The native-client follow-up captures SO_PEERCRED and SO_PEERPIDFD from the accepted Wayland socket before inserting it. The latter pins the original connecting process through the kernel's stored peer reference, rather than looking up its numeric PID later. authenticated_client_pid reads either that original native identity or the original service-channel snapshot; its service-only companion still rejects native connections. Unsupported socket options and missing credentials leave identity unknown while permitting the ordinary display connection. These records confer no IME, provider, capture or input role.

Native tests connect a genuinely separate child process to a Unix listener and require its pinned identity to expire on exit. A socketpair test separately requires ordinary client state without an IME or service role. This follow-up is awaiting Rust/GTK/native VM execution and shipping-kernel qualification. It does not publish sandbox identities or implement X11 process attribution. Kernel contract: Linux 6.5 SO_PEERPIDFD implementation.

Introspect desktop dimensions​

org.gnome.Shell.Introspect.ScreenSize follows the bounding logical desktop layout rather than selecting the primary monitor. The compositor publishes the same logical output inventory used for placement, translating negative origins for the size calculation and including gaps; mirrored output geometry is counted once. Empty output layouts return zero dimensions, and calculations use wider intermediates with the D-Bus signed-integer limit. Initial reads use the current layout even before the service thread starts.

The runtime emits standard PropertiesChanged notifications only when the effective dimensions change. The candidate graphical G-INTROSPECT-SIZE journey subscribes a real Gio client before GNOME ApplyMonitorsConfig, then checks initial property reads and the actual fractional-scale/restoration notifications. Headless compositor-state regressions separately cover negative origins, primary changes, logical resizing, mirrored layouts, translations, disconnects and coordinate extremes. Current-head execution must pass before qualification; this does not establish shipped-image multiple-output, rotation or physical hotplug acceptance in #411/#342.

Transient application association​

A transient dialog belongs to its ultimate mapped parent application, including a picker from a separate provider process. The manager follows actual native/foreign parent relationships or mapped X11 transient XIDs. Cycles fall back to the original window and unknown/unmapped parents are not followed. Runtime snapshots retain the dialog's raw application ID/X11 class separately from the inherited application identity; GetWindows.app-id and running-app focus use the inherited identity. A focused Nautilus picker for Text Editor therefore contributes focus to Text Editor while its raw client metadata remains Nautilus. Withdrawing its imported parent restores the picker's own application identity. Anonymous applications share the ultimate parent's stable window identity.

This metadata association grants no input, capture or provider role. The new regression drives genuinely different parent/dialog/provider app IDs through real Wayland parent assignment, foreign import/withdrawal and unmapping; map tests verify app focus and preserved X11 class. These regressions executed successfully at candidate aabb55e; the integrated main-based source must pass its own CI gates. Full registered desktop-file/StartupWMClass, startup/PID and authenticated sandbox identity resolution, admitted portal app/window selection and final shipped-image qualification remain required under #410/#397. Reference: GNOME Shell 51 WindowTracker.

Trusted Wayland dialogs for X11 parents​

Candidate source implements the pinned libgxdp mutter_x11_interop version 1 contract. Only connections admitted through the authenticated typed service method can see/bind it; ordinary native, ordinary options-based service and IME connections do not gain this capability. This is separate from provider/capture/input permission. Owned live xdg surfaces can request an existing managed X11 parent while unlocked. Invalid or destroyed parents are ignored, and deferred requests retain the original managed window generation rather than resolving a reusable XID later.

The unified parent lookup is used by placement, stacking, modal focus, standalone eligibility and inherited application identity. A dialog shares its parent's workspace and centers over it after the initial buffer determines its size. Parent unmap clears the association; closing a focused dialog returns focus to the surviving parent. Managed parents need not already have an associated Wayland buffer. Preferred scale follows the placed dialog geometry.

A registry regression distinguishes typed service admission from ordinary service liveness and native clients. The reference image adds rootless Xwayland and repeats real Nautilus Open/Save cancel/accept with an actual GTK X11 caller: it retains the XID and managed parent identity, requires centered placement, dialog focus and inherited app association, and requires focus returning to the still-live parent. Earlier four parentless reference outcomes remain part of the suite. All new execution remains pending; these source/tests do not close #404. Multiple simultaneous parents, parent/provider teardown and restart races, locked-session interactions, sandbox document grants and final shipped-image/multiple-output qualification remain required.

Upstream behavior and wire provenance: Mutter 51 interop capability filter, typed service capability, pinned libgxdp XML.

Qualified reference evidence: #406 at 8ac36e67 passed all four actual installed Nautilus Open/Save acceptance/cancellation journeys in portal-security and merged after all fourteen required gates. #416 at c7648e5d passed original native process-identity coverage plus GTK and native VM lifecycle/security gates and merged. These results establish those tested foundations; full sandbox publication, application tracking, dialog parenting and final shipped-image acceptance remain open. Parent-association regressions at 161c2e69 also executed successfully; this newly integrated source requires its own qualification.

At candidate 8b68365f, the actual GTK G-INTROSPECT-TYPES journey changed all fourteen EWMH types and restored the absent-type default successfully; the complete GTK journey and all four X11 scale/input cases passed. DRM output and 240 ordered presentations also passed. This integrated follow-up needs fresh gates, and the earlier 5eda7c96 D-OUTPUT failure has not been assigned a proven root cause.

At candidate b68bad53, actual instrumented coverage passed both typed/ordinary/native registry visibility and the ordinary-client raw blind-bind denial test. The original peer credential snapshot and typed X11 capability are retained separately in the integrated client state. Real X11-parent picker journeys and fresh integrated-head qualification remain pending.

Optional GNOME sandbox identities (#410)​

Native and service-channel connections schedule bounded background discovery from their original live process pin. Flatpak identity uses /proc/PID/root/.flatpak-info and GLib's actual GKeyFile [Application] name parser; Snap identity uses the kernel /proc/PID/attr/current profile, with GNOME's namespace/binary normalization. No identity is inferred from a client-supplied application ID or X11 class. Missing, malformed, inaccessible or oversized metadata leaves the optional field absent. Four workers and a 32-entry nonblocking queue bound discovery work; peer filesystem access never runs in the compositor loop.

GetWindows and eligible running applications expose sandboxed-app-id independently of desktop application association. Cached publication still requires the original process pin to be live. X11 windows remain unknown here: their Wayland peer is Xwayland, not the application. Metadata grants no provider, capture, IME or X11 interoperability authority. Tests exercise real GKeyFile parsing, bounded file/FIFO/symlink handling, missing-pin denial, optional D-Bus fields and expiration of cached fixture metadata through a real service surface. Current-head Rust execution, actual Flatpak/Snap process discovery, sandbox document grants and shipped-image qualification remain pending; #410/#395/#397 remain open.

Contracts: Mutter 51 sandbox discovery and GNOME Shell 51 Introspect fields.

Introspect under org.gnome.Shell for the Background portal (#410)​

xdg-desktop-portal-gnome 51's Background implementation (background.c) makes its Introspect proxy on bus name org.gnome.Shell, object /org/gnome/Shell/Introspect, calls GetRunningApplications for Background.GetAppState (apps without sandboxed-app-id are skipped) and subscribes to RunningApplicationsChanged there. Its screencast picker uses org.gnome.Shell.Introspect. GNOME Shell 51 owns both names on one connection and exports one object (js/misc/introspect.js). In a Marlin VM on main, the GTK shell owned org.gnome.Shell without that object: dbus-monitor showed UnknownMethod: Object does not exist at path /org/gnome/Shell/Introspect, and GetAppState failed with "Could not get window list".

The GTK shell now exports the object on its org.gnome.Shell connection as a relay (shell-gtk/src/introspect_forward.rs) with no window state and no policy. GetRunningApplications and GetWindows go to the compositor's private org.tuna.Introspect (GetRunningApplicationsFor/GetWindowsFor) with the original caller's unique name. The compositor answers only when the relay is the supervised shell's PID and that caller passes the direct rule: shell PID or the installed portal executable owning the GNOME portal name, nothing while locked (Authority::admit_forwarded). Replies and D-Bus errors pass back unchanged. Properties are read through to the compositor, and its RunningApplicationsChanged, WindowsChanged and Introspect PropertiesChanged are re-emitted from the org.gnome.Shell owner. The compositor's version property now has GNOME's lowercase name. Names are shared in tuna_shell_control::introspect.

The other option was a relay in the shell that authenticates callers itself. That would duplicate the admission policy in a second process and let it drift. A compositor-owned org.gnome.Shell would move the shell's whole GNOME interface. crates/compositor/tests/introspect_shell_name.rs compiles the real relay against the real service and Authority on a private dbus-daemon. In it, an admitted caller reads sandboxed-app-id and properties through org.gnome.Shell. A separate process that owns the portal name but is not the installed binary is denied, both through the relay and when calling org.tuna.Introspect directly in another caller's name. A locked session is denied, and change signals reach an org.gnome.Shell subscriber. Installed-portal Background.GetAppState in the VM remains to be qualified; #410 stays open.

Contracts: xdg-desktop-portal-gnome 51 background.c, GNOME Shell 51 introspect.js, org.gnome.Shell.Introspect.xml.

Native Wayland caller reference coverage (#404)​

The reference driver additionally creates an actual native GTK caller, exports its live toplevel through GdkWayland's asynchronous export_handle, and passes that returned wayland: handle to the real portal. Its ordinary socket connection is independent of the typed Nautilus provider connection. The caller uses a distinct raw app ID only to locate its own mapped debug window; that label grants no authority. Open/Save cancel/accept retain the exported handle, actual provider identity, parent association/centered geometry, positive parent input before the dialog, blocked exposed-parent input while modal and restored focus/input after the response. The caller releases its exported handle through drop_exported_handle.

The existing four parentless and four X11-parent outcomes remain required. These new native Wayland journeys are candidate coverage awaiting actual execution, not a claim of full picker, lifecycle, sandbox grant or final shipping-image qualification. API contract: GTK Wayland toplevel export.

The reference-container Files journey also launches the genuine installed Nautilus browser on a fresh directory owned by the ordinary session user. Actual desktop input creates a folder, copies a selected file through the clipboard, renames it, moves it, sends it to Trash, restores it through Undo and closes the browser. Exact file bytes and source/destination paths are verified independently; Trash is enumerated through its actual GIO backend with original-path and contents checks. Accessibility and painted screenshots are retained at each stage, including failures. This supplements picker proofs without establishing final-image, Flatpak, network-volume, scaling or lock-recovery acceptance for the full Files application. The shortcuts follow GNOME copy/move, rename and Trash documentation.

The reference file-picker journey also covers caller-initiated Request.Close for Open and Save with parentless, X11 and native Wayland callers. It first observes the actual focused Nautilus dialog (and the modal parent input block when parented), then closes the request from the original caller connection. The original dialog must disappear, ten fresh GLib timer observations must remain free of a response signal, and Save must leave no destination. Parented cases must restore focus and actual pointer delivery. This follows the public Request contract, which distinguishes caller abort from a user cancellation response. Retained reference-container evidence remains separate from shipped-image, Flatpak, provider-restart and physical-hardware qualification.