Add greeter/session-launch architecture, clarify scope boundary

WayRay is a compositor, not a DE or login system. GNOME/KDE cannot run on WayRay (they ARE compositors). The desktop is composed from independent Wayland clients (pluggable WM + panel + launcher + apps). - ADR-010: Greeter as Wayland client, external session launcher handles PAM/user env (like greetd for Sway) - Clarify scope: WayRay owns compositor session + token binding, not user auth, home dirs, or environment setup - Update roadmap with greeter phase and session.toml config - Update architecture overview with scope boundary section
2026-04-10 13:10:41 +00:00 · 2026-03-28 21:35:18 +01:00 · 2026-03-28 21:35:18 +01:00 · a373ea1c41
commit a373ea1c41
parent 167c6c17c6
4 changed files with 225 additions and 7 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -43,6 +43,9 @@ WayRay consists of four main components:
 - **Headless-first**: No hard dependency on GPU, DRM, or Linux-specific subsystems
 - **illumos + Linux**: Portable core, platform-specific backends behind feature flags
 - **Pluggable Window Management**: External WM process via custom Wayland protocol (River-inspired two-phase transaction model). Ships with built-in floating WM as default.
+- **Compositor, not a DE**: Cannot run GNOME/KDE (they ARE compositors). Desktop composed from independent Wayland clients (WM + panel + launcher + apps). Like Sway's ecosystem.
+- **Greeter as Wayland client**: Login screen is a regular Wayland app, not a separate compositor. External session launcher handles PAM/user env (like greetd for Sway).
+- **WayRay does NOT own**: user auth, home dir mounting, PAM, user environment setup. Those are the host system's job. WayRay owns the compositor session and token binding.
 - QUIC over TCP for network transport (multiplexing, 0-RTT reconnect)
 - PixmanRenderer for headless server (no GPU needed), GlesRenderer when GPU available
 - Damage-tracked differential frame encoding
--- a/docs/ai/adr/010-greeter-session-launch.md
+++ b/docs/ai/adr/010-greeter-session-launch.md
@ -0,0 +1,169 @@
+# 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:
+
+```toml
+# 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
--- a/docs/ai/plans/001-implementation-roadmap.md
+++ b/docs/ai/plans/001-implementation-roadmap.md
@ -102,18 +102,33 @@
 - Session storage: in-memory with optional persistence (SeaORM + SQLite)
 - Session timeout and cleanup policies

-### 3.2 Authentication
- Token-based session identification (smart card ID, badge, or software token)
- PAM integration for user authentication
- Session-token binding in session store
+### 3.2 Greeter and Session Launch
+- Define session launcher interface (events over Unix socket: session_requested, session_authenticated, session_logout)
+- Implement reference session launcher (`wayray-session-launcher`) that:
+  - Receives "new session needed" events from WayRay
+  - Creates user environment (delegates to PAM, system tools)
+  - Starts WayRay compositor session for the user
+  - Launches greeter as first Wayland client
+- Implement reference greeter (`wayray-greeter`) as a Wayland client:
+  - Login form (username + password)
+  - Authenticates via PAM through session launcher
+  - On success, session launcher starts user's configured session (WM, panel, apps)
+  - Greeter exits
+- User session config: `~/.config/wayray/session.toml` (WM, panel, launcher, autostart apps)
+- Support `wlr-layer-shell` protocol for panels, launchers, notification daemons

-### 3.3 Hot-Desking (Session Mobility)
+### 3.3 Token-Based Session Identity
+- Token-based session identification (smart card ID, badge, or software token)
+- Session-token binding in session store
+- WayRay does NOT own authentication -- delegates to session launcher / PAM
+
+### 3.4 Hot-Desking (Session Mobility)
 - Token insertion triggers session lookup across server pool
 - Session reconnection: rebind existing session to new client endpoint
 - Session disconnect: unbind from client, keep session running
 - Sub-second reconnection target (< 500ms)

-### 3.4 Multi-Server Support
+### 3.5 Multi-Server Support
 - Server discovery protocol (mDNS or custom)
 - Session registry: which sessions live on which servers
 - Cross-server session redirect
--- a/docs/architecture/overview.md
+++ b/docs/architecture/overview.md
@ -145,6 +145,34 @@ Frame encoding adapts to content type and network conditions:
 4. Client captures microphone, encodes to Opus, sends to server
 5. Server feeds decoded audio into PipeWire virtual source

+## Scope Boundary: What WayRay Owns
+
+WayRay is a compositor, not a desktop environment or login system.
+
+**WayRay owns:**
+- Wayland compositor (rendering, protocol, encoding, transport)
+- Session lifecycle (active, suspended, resumed, destroyed)
+- Token-to-session binding
+- Pluggable WM protocol
+
+**WayRay does NOT own:**
+- User authentication (PAM, LDAP, Kerberos)
+- User environment (home dirs, mounts, shell, env vars)
+- Desktop environment (WayRay cannot host GNOME/KDE -- they are compositors)
+
+**The desktop experience** is composed from independent Wayland clients:
+- Window manager via `wayray_wm_manager_v1` protocol (floating, tiling, custom)
+- Panel/taskbar (waybar, etc.) via `wlr-layer-shell`
+- App launcher (fuzzel, wofi) via `wlr-layer-shell`
+- Notification daemon (mako, fnott) via `wlr-layer-shell`
+- Any Wayland or X11 application
+
+**Login flow** is handled by an external session launcher (like greetd for Sway):
+1. Token arrives, no session exists
+2. Session launcher creates user environment (PAM, mounts)
+3. Greeter (a Wayland client) authenticates the user
+4. Session launcher starts user's configured session (WM, panel, apps)
+
 ## Comparison with SunRay

 | Feature | SunRay | WayRay |
@ -153,8 +181,11 @@ Frame encoding adapts to content type and network conditions:
 | Compositor | X server (Xnewt) | Wayland (Smithay) |
 | Client Hardware | Purpose-built DTU | Any Linux/macOS/Windows device |
 | Session Mobility | Smart card | Pluggable tokens (smart card, NFC, software) |
+| Login Screen | dtlogin (X11 client) | wayray-greeter (Wayland client) |
+| Desktop | CDE/GNOME on X11 | Composable: pluggable WM + panel + launcher |
 | Audio | Custom ALP channel | Opus over QUIC |
-| USB Forwarding | Custom | USB/IP or usbredir |
+| USB Forwarding | Custom | Userspace over QUIC |
 | Encryption | Optional ALP encryption | Mandatory TLS 1.3 |
 | Multi-server | Failover groups | Distributed session registry |
+| Platform | Solaris | illumos + Linux |
 | Client OS | Proprietary RTOS | Native application |