Skip to main content

security model

This is the entry point for security review of Tuna Desktop. It collects the trust boundaries, the properties the design enforces and the gaps that remain. Component deep dives are linked from each section. Report vulnerabilities through SECURITY.md, not public issues.

Status. Tuna Desktop is a developer preview. The architecture's first delivery tier (nested developer preview) is explicitly "not a secure daily-driver session" (architecture). The ADR register still lists the same-UID threat model, trusted lock/portal identity and the production lock/auth and portal/capture grant lifecycle as open 1.0 release blockers. Everything below describes what the code on main does today. Planned behaviour is labelled target.

What is protected​

  • Screen contents. Pixels of other applications, through capture, screenshots, screen casts and remote desktop.
  • Input. Keystrokes and pointer events belong to the focused client. Nothing may inject input for another client without consent.
  • The lock. While the session is locked, no application surface is shown or receives input, and only the session user's own credentials unlock it.
  • Window metadata. Window titles and application identities are private. They are published only to the supervised shell (its window list and ext_foreign_toplevel_list_v1) and the portal's picker.
  • Shell authority. Commands sent over the shell control socket can focus or close windows, drive the overview and engage the lock. Only the supervised shell may hold a session on that socket.

Adversaries in scope​

  1. Ordinary Wayland clients, sandboxed or not. They may send arbitrary protocol requests, claim any app ID or title, and connect and disconnect at will. They must not capture the screen, type into other clients, see other windows' contents, place shell layers or get past the lock.
  2. Session-bus callers. Any same-user process on the session bus may call the compositor's and shell's D-Bus interfaces, and may claim well-known names that nobody owns yet. Capture, remote input and window introspection must not be granted on the strength of a claimed name.
  3. Processes of other users. They must not reach the control socket or any per-session state.
  4. A person at a locked screen. They can type and click on the lock surface. Lock failure must never expose application surfaces or send input to them.
  5. Hostile extension scripts (see extensions). They must not reach the filesystem, network, processes, input or window contents.
  6. A crashing, hung or malformed shell. Shell faults must not take applications down or block the compositor. A malformed control stream must not crash or stall the compositor.

Out of scope​

  • Same-UID processes that can debug or rewrite the shell or compositor. ADR 0005 records that a process able to ptrace the shell "still wins; that is the platform's same-uid boundary, not something a socket can fix" (ADR 0005). The same applies to a same-user process that edits the user's configuration, autostart entries or extension directory.
  • root, the kernel, GPU drivers and firmware. Executable-identity checks trust root-owned, non-writable installed binaries (see below), so a root compromise defeats them by design.
  • Platform services: GDM, logind, PAM and its modules, polkit and its setuid helper, NetworkManager, BlueZ, fprintd, PipeWire, xdg-desktop-portal and the GNOME portal backend. Tuna Desktop authenticates who it talks to but does not defend against these components misbehaving.
  • Physical attacks beyond the lock screen: DMA, cold boot and similar.
  • Network attackers. The compositor and shell expose no network listener. Network-facing remote desktop belongs to the portal/daemon stack; see Remote desktop.
  • GNOME Shell extensions and private Mutter APIs. They are not loaded or supported (architecture).

Components and trust boundaries​

ComponentTrusted forHow the compositor recognises itCode
Kernel, logind, libseatDevice access, session activityPlatformcrates/compositor/src/drm.rs, logind_session.rs
GDMLogin authentication; starts tuna-session from share/wayland-sessions/tuna.desktopPlatform. Since #866 GDM is the only supported login path. Tuna Desktop ships no greeter.share/wayland-sessions/tuna.desktop
tuna-compositorEverything below. Owns focus, stacking, input routing, the lock flag, capture authorization and privileged protocol exposure (architecture)The trusted computing base of the sessioncrates/compositor
Private PAM helperRunning the tuna-lock PAM transactionRe-executes the compositor's own held image. It never takes an executable path from UI, environment or configuration (private PAM helper).crates/compositor/src/pam_helper.rs
Supervised shell (tuna-shell-gtk by default, legacy tuna-shell-host)UI intent, lock surfaces, layer surfaces (panel, overview, banners, dialogs), the shell's own capture UIPID of the compositor's own shell child (Authority::publish, runtime.rs:4881-4890); for its Wayland connection, the accepted peer's PID at connect time (runtime.rs:1169-1171). Between restarts no process is trusted.crates/shell-gtk, crates/shell-host
Compositor's IBus bridgeTyping for other clients (virtual keyboard)A Wayland connection the compositor inserts itself with the ime_bridge flag (ime.rs:360, lib.rs:328-331)crates/compositor/src/ime.rs
GNOME portal backend (xdg-desktop-portal-gnome)Consent broker for ScreenCast, Screenshot and RemoteDesktopCaller's bus-authenticated PID resolves to a root-owned, non-group/world-writable installed executable, and the caller currently owns org.freedesktop.impl.portal.desktop.gnome (capture_security.rs:176-277)crates/compositor/src/capture_security.rs
GNOME providers (Nautilus file chooser, global-shortcuts provider)Opening an ordinary display connection, and mutter_x11_interopSame installed-executable check for the requested service type only (capture_security.rs:9-40). Confers no capture or input authority (service channel).crates/compositor/src/mutter.rs:198-293, x11_interop.rs
ApplicationsNothing beyond their own surfacesOrdinary clients. Discovered Flatpak/Snap identity is metadata only (service channel).crates/compositor/src/sandbox_identity.rs
Extension scripts (current)A bar cell, a dock badge and notes in the legacy shellIn-process Rhai inside tuna-shell-hostcrates/shell-host/src/extensions.rs
Extensions (target)Declared capabilities onlySeparate processes behind a capability broker. Not implemented.extensions

Shell control socket​

The compositor and shell talk over a dedicated Unix socket with a versioned, length-prefixed postcard protocol (ADR 0002, crates/shell-control-schema). ADR 0005 sets three layers of protection. First, the socket exists only in a private XDG_RUNTIME_DIR with mode 0600. Second, SO_PEERCRED is read before any state is sent, and other UIDs are refused. Third, once supervising, the compositor admits only the supervised child's PID, with at most eight pending peers (crates/compositor/src/control.rs:1602-1660, 1785-1803, 2297). Decoding rejects frames over 1 MiB before postcard runs, and also rejects trailing bytes, over-long titles, oversized collections and a foreign major version (crates/shell-control-schema/src/lib.rs:1965-2015). Evidence: crates/compositor/tests/peer_auth.rs, handshake.rs, control.rs.

The shell is trusted for intent, not authority. It cannot unlock by itself. A client's unlock_and_destroy never unlocks the session: the compositor unlocks only after PAM verifies the password and the compositor clears its own flag (crates/compositor/src/session_lock.rs:1-11).

Lock and authentication​

Lock state lives in the compositor. Only the supervised shell's lock request is approved, and only the approved client's lock surfaces are shown (session_lock.rs:58-110). Engaging the lock does four things: it cancels pending accelerators, stops held remote-desktop input, publishes the locked state to the capture authority and closes the overview (runtime.rs:1661-1687). Unlock runs the session user's own PAM transaction against the tuna-lock service (share/pam.d/tuna-lock) in a private helper. Attempts are bound to the control connection, request, attempt serial and lock epoch. See:

Unlock keyboard boundary (#939)​

The authoritative compositor unlock transition performs a one-shot WindowManager::unlock_input handoff. It restores seat keyboard focus through the normal no-raise focus policy, respecting overview ownership, exclusive layer surfaces and popup grabs rather than unconditionally focusing or raising the remembered application. Session input does not depend on a later pointer motion to recover focus.

Before restoring focus, the compositor quarantines every physically held seat key and removes it from the forwarded pressed-key set. The new keyboard owner's enter event therefore excludes lock-held keys. Quarantine suppresses their repeats and eventual releases for ordinary session clients and shortcuts until genuine key-up; a fresh press can then route normally. Physical pressed state and XKB state remain intact, without synthetic modifier releases.

This boundary does not hide password keys from the user's trusted assistive technology. The same-UID, unreaped compositor-owned Orca process must own org.gnome.Orca.KeyboardMonitor; delivery targets only its admitted unique bus owner. Its keyboard interception runs before ordinary-session filtering, including post-unlock quarantine, so it receives genuine presses and held-key releases while its watches and grabs remain effective across lock/unlock. Those events are not permission to forward input to ordinary session clients.

The reference is Mutter 51.1's meta_a11y_manager_notify_clients: it does not redact password key content or gate keyboard monitoring on lock state. GNOME Shell 51.1's screen shield instead takes a lock-screen modal stage grab. Trusted AT visibility and ordinary-client isolation are separate policies; see screen reader keys while locked. This describes the input boundary, not a new test or CI receipt.

Capture, screenshots and remote desktop​

Only the supervised shell or the authenticated installed portal backend may create ScreenCast sessions, take screenshots or create RemoteDesktop sessions (Authority::authenticate_caller, capture_security.rs:220-245). Claiming the portal's bus name alone is not enough. Sessions belong to their unique creator, are single-use, and are bounded at 256 sessions and 64 streams per session. Revocation is permanent. A 100 ms scan on the D-Bus thread revokes a grant when its owner disconnects, the trusted portal name changes hands, the shell PID changes or the session locks (mutter.rs:1339-1392). Capture paths also refuse locked frames. Full detail and the qualification evidence: capture admission and revocation, remote desktop, input capture, screenshot consent.

Privileged Wayland globals​

  • zwp_virtual_keyboard_manager_v1 is visible only to the compositor's IBus bridge (protocols.rs:171-181).
  • zwlr_layer_shell_v1 is visible and bindable only to the supervised shell's connection (#1048). The compositor marks a native connection as the shell's when it accepts it, if the peer is the shell child it spawned and still holds: the pidfd-pinned peer process, or the SO_PEERCRED PID where the kernel has no SO_PEERPIDFD (lib.rs:383-396, layer.rs:55-61, runtime.rs:1169-1171). The global filter hides it from every other client and a blind bind by name is a protocol error (lib.rs:1099-1107). Shell surfaces are still told apart by namespace, but only the shell can create one. Evidence: crates/compositor/tests/protocols.rs (layer_shell_is_visible_and_bindable_only_by_the_supervised_shell).
  • mutter_x11_interop is visible only to typed service-channel connections (x11_interop.rs:65-67).
  • ext_foreign_toplevel_list_v1 (every window's title and app id) is visible and bindable only to the supervised shell's connection, with the same filter as layer-shell (#1046). Evidence: crates/compositor/tests/protocols.rs (the_shell_lists_toplevels_until_they_close_and_apps_cannot_bind_the_list).
  • ext_session_lock_manager_v1 is advertised to every client outside a security context, but a lock is granted only to the supervised shell's PID (session_lock.rs).
  • wp_security_context_manager_v1 lets a sandbox engine (Flatpak) open a listener whose clients join tagged with the context (#1046). Every privileged global's filter (ClientState::privileged: virtual keyboard, input method, mutter_x11_interop, layer-shell, the foreign toplevel list) refuses such a client whatever its other state, and it sees neither the session lock nor the manager itself, so it cannot nest a context. Evidence: crates/compositor/tests/protocols.rs (security_context_clients_see_no_privileged_global). A connection the listener cannot accept (no descriptor left: EMFILE, ENFILE) rests the listener 250 ms and is retried, instead of ending the event loop and the session (#1071, security_listener.rs; crates/compositor/tests/security_context_accept.rs).
  • Input-method v2 is open to any client, as on GNOME (protocols.rs:165-166).

Session-bus interfaces​

Each interface checks its caller itself. The main policies:

InterfaceServed byCaller policy
org.gnome.Mutter.ScreenCast, .RemoteDesktop, org.gnome.Shell.Screenshot, org.tuna.ScreenshotcompositorShell PID or authenticated installed portal. Denied while locked.
org.gnome.Mutter.InputCapturecompositorCreateSession: authenticated installed portal only (Authority::admit_portal), not the shell PID. Session methods: the unique owner, denied while locked. Lock closes every session at once; owner loss within the 100 ms scan. No input is captured while locked (input capture).
org.gnome.Mutter.ServiceChannelcompositorSame-user caller. Typed connections require the installed provider for that type.
org.gnome.Shell.IntrospectcompositorShell PID or authenticated installed portal (capture_security::Authority::admit). Denied while locked. TUNA_INTROSPECT_UNRESTRICTED=1 (test/development "unsafe mode") allows metadata only while unlocked (introspect.rs).
/org/gnome/Shell/Introspect on org.gnome.ShellGTK shell relays to the compositorThe shell holds no window data and decides nothing: it forwards each call to the compositor's org.tuna.Introspect with the original caller's unique name. The compositor answers only when the relay is the supervised shell's PID and the original caller passes the org.gnome.Shell.Introspect rule above (Authority::admit_forwarded; shell-gtk/src/introspect_forward.rs).
org.gnome.Shell (OSD, search, app grid)GTK shellCaller must own org.gnome.Settings, org.gnome.SettingsDaemon.MediaKeys or the GNOME portal name, as GNOME's DBusSenderChecker. TUNA_SHELL_DBUS_UNRESTRICTED=1 disables this for harnesses (shell-gtk/src/shell_dbus.rs:27-31, 374-378).
org.gnome.Shell.NetworkAgent (system bus)GTK shellOnly NetworkManager's current unique owner (network agent).
org.freedesktop.impl.portal.Accessshell (org.freedesktop.impl.portal.desktop.tuna)Always answers "cancelled", so the requester is refused (shell-host/src/lockdown.rs:66-83).

Neither UNRESTRICTED variable is set by the packaged session (share/wayland-sessions/tuna.desktop, crates/compositor/src/bin/tuna-session.rs).

Native CI reference observer (not product authority)​

packaging/marlin/vm-lane/tuna-vm-gnome-reference is a fixed, finite CI fixture, not a capture grant or a product authorization mechanism. Its root controller owns /proc executable/start-generation observations and private receipts. Its UID1000 child reads existing public Gio settings and AT-SPI objects only. Same-UID access to /proc/<pid>/exe is not assumed: an actual bus daemon can be non-dumpable without invalidating that daemon. The fixture does not change dumpability, ptrace policy, proc mounts or bus security policy.

The child inherits one private packet socketpair, with no listener or host service. Each request is bound to the spawned child's kernel SCM_CREDENTIALS and independently pinned process generation; socketpair SO_PEERCRED identifies its creator and is not used as sender identity. Requests cannot supply a PID, executable, command or arbitrary bus address. Only the existing admitted session bus and the accessibility address independently read from its pinned org.a11y.Bus owner are eligible. Session-bus owner queries are limited to that launcher and Mutter DisplayConfig. Accessibility owner queries are limited to the registry and unique application names in its actual root inventory, refreshed for later fixture launches.

For a socket observation the child transfers exactly one connected Gio FD. The controller only inspects its address and kernel SO_PEERCRED; it never reads, authenticates or issues D-Bus calls on the child's stream. It compares that peer with its own independently connected fixed bus and original process/socket pins. Separate root-owned read-only, no-autostart connections resolve exact bus owners to UID/PID and /proc executable/hash/start/boot identities before and after observation. Returned child receipts must match those independent identities. Truncated packets, foreign senders, extra or missing FDs, changed peers and unobserved owners fail closed; received FDs are closed on success and failure. Packets are bounded to 64 KiB, requests to 12010, trees to 6000 nodes, and all work shares the existing at-most-25s operation deadline, including connection authentication.

The first terminal operation failure is retained through stop and missing file probes; the host retrieves it before probing other receipts. This preserves cause, not a pass: run 41490837174's Tuna reference artifact 13168047462 recorded the UID1000 /proc/1789/exe permission failure. The GNOME artifact 13166824093 retained only a later missing snapshot.json file error after its original prepare failure was overwritten. Its original cause cannot be recovered from the retained member, serial command trace or job log. Controlled semantic regressions are not native qualification; fresh actual reference evidence and physical UI classification remain required for both legs.

Current state compared with the target​

AreaToday on mainTarget
ExtensionsRhai scripts run in-process in the legacy tuna-shell-host only. The default GTK shell loads none. Containment is a language sandbox with an operation budget.Separate, untrusted processes behind a capability broker, with no privileged Wayland socket, native plugin ABI, raw input, clipboard, capture, filesystem or network by default (architecture, extensions)
Shell identityPID of the compositor's child, checked on the control socket and for captureInherited pre-connected socketpair or another production credential, deferred to spek 004 (ADR 0005)
Shell supervisionCompositor-owned child with a finite restart budget and capped backoff (ADR 0003, supervise.rs)Production supervision and identity are a 004 gate
Activation tokensCompositor-minted, one-use, 30 s, seat and app-ID bound (ADR 0002)Binding to xdg_activation external tokens deferred to 004
Portal grantsConsent by the GNOME backend; compositor-enforced, revocable grants (above)Complete grant lifecycle reviewed; open release blocker in the ADR register

Known limitations​

  • Same-UID boundary. PID-based shell identity and executable-identity checks stop name spoofing. They do not stop a same-user process that can ptrace or inject into the shell or portal.
  • Name-based allowlists. The org.gnome.Shell allowlist trusts whoever owns an allowlisted well-known name, as GNOME does. A same-user process that claims org.gnome.Settings first passes it. Those methods only show OSDs and open search or the app grid.
  • Extension sandbox is in-process. The Rhai engine sets an operation budget but no string, array or memory limits (extensions.rs:103-146), so a script can exhaust the legacy shell host's memory. A Rhai engine bug is a shell host bug. The compositor is unaffected: the shell is a separate, supervised process.
  • Revocation latency is the 100 ms scan plus one compositor tick. This is not a hard real-time bound under CPU starvation (capture security).
  • Hardware. Qualification covers the Marlin VM, vkms and CI. The physical GPU/support matrix is open (architecture).
  • Sandboxed app identity is best-effort metadata, unqualified for shipped Flatpak/Snap processes, and X11 windows have none (service channel).

Release gates​

These must pass before the security claims above can be called release quality:

  • The architecture's cross-cutting gates: apps survive shell and extension crashes, lock failure never exposes surfaces or redirects input, and capture and remote input use portal consent with compositor-validated authorization (architecture).
  • Roadmap decision gate 4: the threat model assigns trusted identities and lock/auth/portal/capture authority end to end, and specialist review leaves no unresolved critical issue. Gate 5: before 1.0, no critical lock/capture/input/clipboard/IME regression. Gate 6: before public extensions, broker containment criteria pass (roadmap).
  • Requirements R6 (session/lock), R11 (extension boundary) and R14 (capture/privileged surfaces) with their security cases (requirements).
  • The open ADR register rows for same-UID identity and the production lock/auth and portal/capture lifecycle (ADR register).

The portal-security and remote-security CI lanes run the packaged compositor and GTK shell against the installed GNOME portal stack (scripts/tuna-portal-security, testing). Their evidence manifests are capture-evidence.json and capture-security-evidence.json.