wayray/docs/ai/adr/010-greeter-session-launch.md

ADR-010: Greeter and Session Launch Architecture

Status

Accepted

Context

WayRay is a compositor, not a login manager. But thin clients need a login screen -- when a token arrives with no existing session, the user must authenticate before getting a desktop. We cannot run GNOME/KDE as desktop environments because they ARE Wayland compositors (Mutter/KWin) and cannot run inside WayRay.

The Wayland DE Problem

On X11, desktop environments were clients of the X server. GNOME, KDE, XFCE all ran on any X server including SunRay's Xnewt. On Wayland, DEs are tightly coupled to their compositor:

DE	Compositor	Can run on WayRay?
GNOME Shell	Mutter	No -- Mutter IS a compositor
KDE Plasma	KWin	No -- KWin IS a compositor
XFCE4 (Wayland)	xfwm4/labwc	No -- needs its own compositor
Budgie (Wayland)	Magpie	No -- needs its own compositor

What DOES work: all individual applications from these DEs (Nautilus, Dolphin, Firefox, etc.) are standard Wayland clients.

Decision

WayRay Does Not Own User Authentication or Environment Setup

WayRay's responsibility boundary:

WayRay owns:

• Wayland compositor (rendering, protocol, encoding, transport)
• Session lifecycle (active, suspended, resumed, destroyed)
• Token-to-session binding (which token maps to which compositor session)
• WM protocol (pluggable window management)

WayRay does NOT own:

• User authentication (PAM, LDAP, Kerberos)
• User environment (home dirs, NFS/ZFS mounts, shell, env vars)
• Desktop environment selection
• System-level session management (logind, zones)

Session Launch Flow

┌──────────┐     token      ┌──────────────┐
│  Client   │──────────────►│  WayRay      │
│  (viewer) │               │  Server      │
└──────────┘               └──────┬───────┘
                                   │
                          Does session exist
                          for this token?
                                   │
                    ┌──────────────┼──────────────┐
                    │ YES                         │ NO
                    v                             v
             Resume session              ┌──────────────┐
             (sub-500ms)                 │ Session      │
                                         │ Launcher     │
                                         │ (external)   │
                                         └──────┬───────┘
                                                │
                                    1. Create user environment
                                       (PAM, mount home, etc.)
                                    2. Start WayRay compositor
                                       session for this user
                                    3. Launch greeter as first
                                       Wayland client
                                                │
                                                v
                                         ┌──────────────┐
                                         │ Greeter      │
                                         │ (Wayland     │
                                         │  client)     │
                                         └──────┬───────┘
                                                │
                                    User enters credentials
                                    Greeter authenticates via PAM
                                                │
                                                v
                                    Launch user's configured
                                    session (WM, panel, apps)
                                    Greeter exits

The Session Launcher

A separate daemon/service (not part of WayRay) that:

1. Listens for "new session needed" events from WayRay
2. Creates the user environment (PAM session, mount home, set env vars)
3. Starts a WayRay compositor session for that user
4. Launches the greeter inside it

This is analogous to:

• SunRay: SRSS session manager + dtlogin
• Sway: greetd + gtkgreet/regreet
• GNOME: GDM + gnome-shell (but GDM IS a compositor; our greeter is a client)

We provide a reference session launcher (wayray-session-launcher) but the interface is a simple protocol/hook so admins can replace it with their own.

The Greeter

A Wayland client application that:

• Displays a login form (username + password, or smart card PIN)
• Authenticates via PAM
• On success, signals the session launcher to proceed with user session setup
• Exits

We ship a reference greeter (wayray-greeter) but any Wayland client implementing the greeter protocol works. Community can build GTK, Qt, or TUI-based greeters.

The User Session (Desktop Experience)

After authentication, the session launcher starts the user's configured environment:

# Example: ~/.config/wayray/session.toml

# Window manager (connects via wayray_wm_manager_v1 protocol)
wm = "wayray-wm-floating"
# wm = "wayray-wm-tiling"
# wm = "/usr/local/bin/my-custom-wm"

# Panel (layer-shell Wayland client)
panel = "waybar"

# App launcher
launcher = "fuzzel"

# Notification daemon
notifications = "mako"

# Autostart applications
autostart = [
    "foot",           # Terminal
    "nm-applet",      # Network manager tray
]

This composes a full desktop from independent Wayland clients:

• WM: Pluggable via our protocol (ADR-009)
• Panel: waybar, ironbar, or custom (layer-shell protocol)
• Launcher: fuzzel, wofi, tofi (layer-shell protocol)
• Notifications: mako, fnott (layer-shell protocol)
• Apps: any Wayland or X11 (via XWayland) application

Integration Points

WayRay exposes hooks for the session launcher:

Event: session_requested(token) -> session_launcher handles it
Event: session_authenticated(user, token) -> launcher sets up user env
Event: session_logout(session_id) -> launcher tears down user env

The interface is intentionally minimal -- a few events over a Unix socket or D-Bus. This keeps WayRay decoupled from any specific auth/provisioning stack.

Rationale

• Separation of concerns: WayRay is a compositor, not a login system. Authentication and environment provisioning vary wildly between deployments (LDAP vs local, NFS vs ZFS, containers vs bare metal). WayRay shouldn't know or care.
• SunRay precedent: SunRay's SRSS managed display sessions. dtlogin handled authentication. Solaris handled user environments. Same separation.
• greetd precedent: The Wayland ecosystem already solved this -- greetd + gtkgreet for Sway proves the external greeter model works.
• Composability: Administrators can swap any component. Corporate deploy with SSO greeter and locked-down session config. University deploy with student self-service. Home user with minimal auto-login.
• Greeter as Wayland client: No special rendering path. The greeter is just the first app that runs in the session. It uses the same compositor, same encoding, same network transport as everything else.

Consequences

• Must define a stable session launcher interface (events/hooks)
• Must ship a reference greeter and reference session launcher for out-of-box usability
• Users expecting "GNOME over thin client" will be disappointed -- we should be clear in docs that WayRay provides a composable desktop, not a DE
• The session.toml concept needs careful design for both simplicity and flexibility
• Must support wlr-layer-shell protocol for panels, launchers, and notification daemons