Make Wayland capture honest and replace the broad input group with least privilege

Phase 3 of the improvement plan (PR 10 of the sequence): honest Wayland
behavior and a least-privilege alternative to the broad `input` group the
audit flagged as a keylogging surface.

Least-privilege input access:
- packaging/linux/common/60-stepforge-input.rules grants the ACTIVE session
  read access to MOUSE devices only (ID_INPUT_MOUSE, excluding
  ID_INPUT_KEYBOARD) via a systemd uaccess ACL — session-scoped, device-
  scoped, and never keyboards. This replaces `usermod -aG input`, which grants
  every input device (keyboards included) to the user permanently.
- scripts/linux/enable-click-capture.sh installs it opt-in: it prints the exact
  rule, requires confirmation, and documents the security tradeoff. It never
  runs the broad-group command.

Honest trigger reporting:
- New chooseCaptureTrigger() (app/platform/linux/diagnostics.js, re-exported
  from app/platform/index.js) maps a capability profile to the real trigger:
  per-click with a marker on X11+xinput; per-click WITHOUT coordinates or a
  marker on Wayland evdev (the platform exposes no pointer position); and an
  honest hotkey/interval fallback otherwise. It never promises per-click
  capture with coordinates on Wayland.
- platform:capabilities now includes the active trigger for the machine and
  the user's fallback setting, for the diagnostics UI.

Docs:
- GETTING_STARTED_WITH_LINUX.md no longer instructs every Wayland user to join
  the `input` group; it presents that as a warning, documents the least-
  privilege script, corrects the capability table (per-click is opt-in, mice
  only; hotkey/interval is the default Wayland trigger), and points at
  Settings → Diagnostics.

Tests: trigger decisions for X11/xinput, Wayland evdev (no coordinates/marker),
Wayland fallback (interval/hotkey with an honest note), the platform facade
wiring, Windows; the udev rule (mouse-only, excludes keyboards, uaccess); the
opt-in enable script (confirms, installs the rule, never runs usermod -aG
input as a command); and docs guards. 289 unit tests pass; startup smoke and
click self-test unchanged (stream, markers 3/3, burst 8/8).

Co-Authored-By: Claude Fable 5 <[email protected]>

app/main.js

@@ -900,8 +900,14 @@ function setupIpc() {
     platform: process.platform,
   }));
   // Platform capture-capability profile (session type, portal/PipeWire,
-  // xinput, click source, actionable messages) for the diagnostics UI.
+  // xinput, click source, actionable messages) for the diagnostics UI, plus
-  h('platform:capabilities', () => require('./platform').detectCapabilities());
+  // the honest active trigger for this machine and settings.
+  h('platform:capabilities', () => {
+    const platform = require('./platform');
+    const caps = platform.detectCapabilities();
+    const activeTrigger = platform.chooseCaptureTrigger(caps, settings.get('capture.fallbackTrigger') || 'interval');
+    return { ...caps, activeTrigger };
+  });
 }
 
 // ---- lifecycle --------------------------------------------------------------

app/platform/index.js

@@ -63,4 +63,19 @@ function detectCapabilities({ platform = process.platform, env = process.env } =
   };
 }
 
-module.exports = { detectPlatform, createWindowContextProvider, detectCapabilities };
+/**
+ * The honest capture-trigger decision for the current capabilities. On Linux
+ * this defers to the diagnostics helper (which never promises per-click
+ * capture with coordinates on Wayland); other platforms have a fixed answer.
+ */
+function chooseCaptureTrigger(capabilities, userTriggerPreference = 'interval') {
+  if (capabilities && capabilities.os === 'linux') {
+    return require('./linux/diagnostics').chooseCaptureTrigger(capabilities, userTriggerPreference);
+  }
+  if (capabilities && capabilities.os === 'windows') {
+    return { trigger: 'click', clickSource: 'windows-hook', coordinates: true, marker: true, note: '' };
+  }
+  return { trigger: 'click', clickSource: capabilities ? capabilities.os : 'unavailable', coordinates: true, marker: true, note: '' };
+}
+
+module.exports = { detectPlatform, createWindowContextProvider, detectCapabilities, chooseCaptureTrigger };

app/platform/linux/diagnostics.js

@@ -96,4 +96,61 @@ function detectLinuxCapabilities({
   };
 }
 
-module.exports = { detectLinuxCapabilities, detectSessionType };
+/**
+ * Decide the honest capture trigger for a Linux capability profile. StepForge
+ * must never *promise* per-click capture with coordinates on Wayland, because
+ * the platform does not expose pointer position to apps. Returns the trigger,
+ * whether clicks carry coordinates, whether a marker can be drawn, and a
+ * user-facing note. `userTriggerPreference` is the capture.fallbackTrigger
+ * setting ('interval' | 'hotkey') used only when no click source exists.
+ */
+function chooseCaptureTrigger(capabilities, userTriggerPreference = 'interval') {
+  const caps = capabilities || {};
+  const click = caps.clickCapture;
+
+  if (click === 'x11-xinput') {
+    return {
+      trigger: 'click',
+      clickSource: 'x11',
+      coordinates: true,
+      marker: true,
+      note: 'Per-click capture with an accurate marker (X11 + xinput).',
+    };
+  }
+  if (click === 'evdev-x11') {
+    return {
+      trigger: 'click',
+      clickSource: 'evdev-x11',
+      coordinates: true,
+      marker: true,
+      note: 'Per-click capture via kernel input devices (X11, no xinput).',
+    };
+  }
+  if (click === 'evdev-wayland') {
+    // Wayland exposes button presses (via evdev, if permitted) but NOT pointer
+    // position, so a step is captured per click but without a marker. This is
+    // only reached when the user opted into the least-privilege device rule.
+    return {
+      trigger: 'click',
+      clickSource: 'evdev-wayland',
+      coordinates: false,
+      marker: false,
+      note: 'Per-click capture on Wayland has no pointer position, so no marker is drawn.',
+    };
+  }
+
+  // No global click source: the safe baseline is the user's chosen fallback.
+  const trigger = userTriggerPreference === 'hotkey' ? 'hotkey' : 'interval';
+  return {
+    trigger,
+    clickSource: trigger,
+    coordinates: false,
+    marker: false,
+    note: caps.isWayland
+      ? 'Wayland does not expose global clicks; recording uses your ' + trigger + ' trigger. '
+        + 'Screen sharing is requested once per recording via the portal.'
+      : 'No global click source available; recording uses your ' + trigger + ' trigger.',
+  };
+}
+
+module.exports = { detectLinuxCapabilities, detectSessionType, chooseCaptureTrigger };

docs/GETTING_STARTED_WITH_LINUX.md

@@ -13,10 +13,11 @@ difference, how to get the best experience, and how to enable per-click capture.
 
 | | **X11 / "Ubuntu on Xorg"** | **Wayland (default on Ubuntu)** |
 |---|---|---|
-| Screenshot per click | ✅ Yes | ✅ Yes (needs `input` group) |
+| Screenshot per click | ✅ Yes | ⚙️ Optional (least-privilege mouse rule) |
 | Red circle on the click | ✅ Yes | ❌ No (Wayland hides the cursor position) |
 | "Share your screen" prompt | Never | Once per recording session |
-| Setup needed | None | Add yourself to the `input` group |
+| Default trigger | Per click | Global hotkey or timed interval |
+| Setup needed | None | None (per-click is opt-in, mice only) |
 
 **If you want the full Windows-like experience (click capture *with* the red
 marker), use an Xorg session — see [Option A](#option-a-best-experience--use-xorg).**
@@ -67,27 +68,30 @@ stream stays open until you stop recording.
 > If you never see steps appear, make sure you actually picked a screen and
 > clicked **Share** in that dialog.
 
-### Per-click capture (requires the `input` group)
+### Per-click capture (optional, least-privilege)
 
-By default on Wayland, StepForge cannot see your clicks, so it falls back to
+By default on Wayland, StepForge cannot see your clicks, so it uses a **global
-**capturing a screenshot every few seconds** (timed capture).
+hotkey or a timed interval** to capture (see below). This is the recommended,
+no-extra-permissions path.
 
-To get a screenshot **on every click** instead, give your user read access to
+If you want a screenshot **on every click**, you can grant StepForge read
-the mouse devices by joining the `input` group:
+access to your **mouse** devices. Do **not** use `sudo usermod -aG input`:
+joining the `input` group grants your user access to *all* input devices —
+**including keyboards** — permanently, on every session. That is a keylogging
+surface StepForge does not need.
+
+Instead, install the least-privilege udev rule, which grants your active
+session read access to **mouse devices only** (never keyboards), scoped to
+whoever is physically logged in:
 
 ```bash
-sudo usermod -aG input "$USER"
+bash scripts/linux/enable-click-capture.sh
 ```
 
-Then **log out and log back in** (group membership only applies to new sessions).
+It shows you the exact rule and asks for confirmation before installing. Under
-Verify it took effect:
+the hood it uses a systemd `uaccess` ACL restricted to `ID_INPUT_MOUSE`
-
+devices — see [packaging/linux/common/60-stepforge-input.rules](../packaging/linux/common/60-stepforge-input.rules).
-```bash
+Re-log in (or replug a USB mouse) for it to apply.
-groups | tr ' ' '\n' | grep input    # should print: input
-```
-
-Now StepForge reads mouse buttons directly from the kernel (`/dev/input`) and
-captures a screenshot on each click.
 
 > **No red marker on Wayland.** Even with per-click capture working, Wayland
 > does not tell apps *where* the pointer is, so StepForge cannot draw the circle
@@ -114,10 +118,16 @@ On launch StepForge chooses the best available click source:
 1. **Windows** — low-level mouse hook (position + timing).
 2. **X11** — `xinput` (position + timing → full red marker).
 3. **Linux evdev** (`/dev/input`) — button presses on X11 *and* Wayland, no
-   position on Wayland. Used when `xinput` can't see clicks (i.e. Wayland), if
+   position on Wayland. Used when `xinput` can't see clicks (i.e. Wayland) and
-   you're in the `input` group.
+   only if you opted into the least-privilege mouse rule
-4. **Timed capture** — the always-works fallback (a screenshot every N seconds)
+   (`scripts/linux/enable-click-capture.sh`).
-   when no click source is available.
+4. **Hotkey / timed capture** — the always-works fallback (the Capture hotkey,
+   or a screenshot every N seconds) when no click source is available. On
+   Wayland this is the default, and StepForge reports it honestly instead of
+   pretending clicks are captured.
+
+Open **Settings → Diagnostics** to see the detected session type, portal/
+PipeWire status, and the active capture trigger for your machine.
 
 Screen frames come from a single long-lived capture stream per recording, so
 clicks/timer ticks never re-open the screen-share dialog.
@@ -149,7 +159,9 @@ STEPFORGE_CAPTURE_LOG=1 npm start
 
 - `[stepforge] screen-capture stream active …` — the stream is up.
 - `[stepforge] per-click capture via evdev on N device(s) …` — clicks are wired up.
-- `[stepforge] no readable mouse input devices …` — you need the `input` group (see above).
+- `[stepforge] no readable mouse input devices …` — per-click capture is not
+  enabled; run `scripts/linux/enable-click-capture.sh` for the least-privilege
+  mouse rule, or just use the hotkey/interval trigger.
 
 **Harmless console noise.** Lines like `vaInitialize failed`, `Frame latency is
 negative`, and `StatusNotifierItem … already exported` come from Chromium/GNOME,

packaging/linux/common/60-stepforge-input.rules

@@ -0,0 +1,19 @@
+# StepForge least-privilege input access (OPTIONAL, opt-in).
+#
+# Grants the user at the ACTIVE local session read/write access to MOUSE input
+# devices only, via systemd-logind's `uaccess` ACL. This is the least-privilege
+# alternative to joining the broad `input` group, which would grant access to
+# ALL input devices — including keyboards — for the user permanently, on every
+# session. StepForge never needs keystrokes, so this rule deliberately EXCLUDES
+# keyboards.
+#
+# Scope of what this grants:
+#   * only devices udev classifies as a mouse (ID_INPUT_MOUSE=1),
+#   * only when they are NOT also a keyboard (ID_INPUT_KEYBOARD!=1),
+#   * only to whoever is logged in at the physical seat (uaccess is
+#     session-scoped, not a permanent group membership).
+#
+# StepForge uses this only for the optional Wayland per-click *trigger* (button
+# presses, no coordinates). It is not required — the safe default is a global
+# hotkey or interval capture.
+SUBSYSTEM=="input", KERNEL=="event*", ENV{ID_INPUT_MOUSE}=="1", ENV{ID_INPUT_KEYBOARD}!="1", TAG+="uaccess"

scripts/linux/enable-click-capture.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# OPTIONAL: enable per-click capture on Wayland (or X11 without xinput) using a
+# LEAST-PRIVILEGE udev rule instead of the broad `input` group.
+#
+# Security tradeoff (read before running):
+#   * This grants your ACTIVE local session read access to MOUSE devices only.
+#   * It deliberately EXCLUDES keyboards — StepForge never needs keystrokes.
+#   * Access is session-scoped (systemd `uaccess` ACL), not a permanent group.
+#   * It is NOT required: the safe default is a global hotkey or interval
+#     capture. Only enable this if you want a screenshot on every click.
+#
+# Compare to `sudo usermod -aG input "$USER"`, which grants access to ALL input
+# devices (including keyboards) for your user on every session — a much larger
+# surface. This script does not do that.
+set -euo pipefail
+
+RULE_SRC="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/packaging/linux/common/60-stepforge-input.rules"
+RULE_DEST="/etc/udev/rules.d/60-stepforge-input.rules"
+
+if [ ! -f "$RULE_SRC" ]; then
+  echo "error: rule file not found at $RULE_SRC" >&2
+  exit 1
+fi
+
+echo "This installs a least-privilege udev rule granting your session read"
+echo "access to MOUSE devices only (never keyboards):"
+echo
+sed 's/^/    /' "$RULE_SRC"
+echo
+printf 'Install it to %s? [y/N] ' "$RULE_DEST"
+read -r reply
+case "$reply" in
+  y|Y|yes|YES) ;;
+  *) echo "Aborted. No changes made."; exit 0 ;;
+esac
+
+SUDO=""
+if [ "$(id -u)" -ne 0 ]; then SUDO="sudo"; fi
+
+$SUDO install -m 0644 "$RULE_SRC" "$RULE_DEST"
+$SUDO udevadm control --reload-rules
+$SUDO udevadm trigger --subsystem-match=input --action=change || true
+
+cat <<'MSG'
+
+Installed. You may need to unplug/replug a USB mouse or re-log in for the ACL
+to apply to already-connected devices.
+
+To remove it later:
+  sudo rm /etc/udev/rules.d/60-stepforge-input.rules
+  sudo udevadm control --reload-rules
+MSG

tests/unit/wayland-honesty.test.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { chooseCaptureTrigger, detectLinuxCapabilities } = require('../../app/platform/linux/diagnostics');
+const platform = require('../../app/platform');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8');
+const exists = (rel) => fs.existsSync(path.join(ROOT, rel));
+
+// ---- honest trigger decisions ----------------------------------------------
+
+test('X11 + xinput promises per-click capture with a marker', () => {
+  const t = chooseCaptureTrigger({ os: 'linux', isWayland: false, clickCapture: 'x11-xinput' });
+  assert.equal(t.trigger, 'click');
+  assert.equal(t.coordinates, true);
+  assert.equal(t.marker, true);
+});
+
+test('Wayland evdev captures per click but never promises coordinates or a marker', () => {
+  const t = chooseCaptureTrigger({ os: 'linux', isWayland: true, clickCapture: 'evdev-wayland' });
+  assert.equal(t.trigger, 'click');
+  assert.equal(t.coordinates, false, 'Wayland exposes no pointer position');
+  assert.equal(t.marker, false);
+});
+
+test('Wayland without a click source falls back to the user trigger, honestly', () => {
+  const interval = chooseCaptureTrigger({ os: 'linux', isWayland: true, clickCapture: 'hotkey-or-interval-only' }, 'interval');
+  assert.equal(interval.trigger, 'interval');
+  assert.equal(interval.coordinates, false);
+  assert.match(interval.note, /Wayland does not expose global clicks/i);
+
+  const hotkey = chooseCaptureTrigger({ os: 'linux', isWayland: true, clickCapture: 'hotkey-or-interval-only' }, 'hotkey');
+  assert.equal(hotkey.trigger, 'hotkey');
+});
+
+test('the platform facade wires the Linux trigger decision from real capabilities', () => {
+  const caps = detectLinuxCapabilities({
+    env: { XDG_SESSION_TYPE: 'wayland', WAYLAND_DISPLAY: 'wayland-0' },
+    hasBinary: () => false,
+    existsSync: () => false,
+    readdirSync: () => [],
+  });
+  const t = platform.chooseCaptureTrigger(caps, 'interval');
+  assert.equal(t.trigger, 'interval');
+  assert.equal(t.marker, false);
+});
+
+test('Windows always reports per-click capture', () => {
+  const t = platform.chooseCaptureTrigger({ os: 'windows' });
+  assert.equal(t.trigger, 'click');
+  assert.equal(t.coordinates, true);
+});
+
+// ---- least-privilege input access -------------------------------------------
+
+test('the udev rule grants mouse-only access and excludes keyboards', () => {
+  assert.ok(exists('packaging/linux/common/60-stepforge-input.rules'));
+  const rule = read('packaging/linux/common/60-stepforge-input.rules');
+  assert.match(rule, /ID_INPUT_MOUSE\}=="1"/);
+  assert.match(rule, /ID_INPUT_KEYBOARD\}!="1"/, 'must exclude keyboards');
+  assert.match(rule, /TAG\+="uaccess"/, 'session-scoped ACL, not a permanent group');
+});
+
+test('the enable script is opt-in and installs the least-privilege rule, not the input group', () => {
+  assert.ok(exists('scripts/linux/enable-click-capture.sh'));
+  const script = read('scripts/linux/enable-click-capture.sh');
+  assert.match(script, /read -r reply/, 'must confirm before installing');
+  assert.match(script, /60-stepforge-input\.rules/, 'installs the least-privilege udev rule');
+  // usermod may only appear in a comment (warning), never as an executed command.
+  for (const line of script.split('\n')) {
+    const code = line.replace(/#.*$/, '');
+    assert.doesNotMatch(code, /usermod -aG input/, 'must not run the broad input-group command');
+  }
+});
+
+// ---- docs no longer push the broad input group ------------------------------
+
+test('Linux docs recommend the least-privilege path and warn against the input group', () => {
+  const doc = read('docs/GETTING_STARTED_WITH_LINUX.md');
+  assert.match(doc, /enable-click-capture\.sh/);
+  assert.match(doc, /least-privilege/i);
+  // The broad group is now presented as a warning ("Do not use ..."), not a
+  // recommended step.
+  assert.match(doc, /Do \*\*not\*\* use `sudo usermod/);
+});