diff --git a/app/main.js b/app/main.js index c02a543..104f783 100644 --- a/app/main.js +++ b/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. - h('platform:capabilities', () => require('./platform').detectCapabilities()); + // xinput, click source, actionable messages) for the diagnostics UI, plus + // 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 -------------------------------------------------------------- diff --git a/app/platform/index.js b/app/platform/index.js index 3829d3f..15f3aec 100644 --- a/app/platform/index.js +++ b/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 }; diff --git a/app/platform/linux/diagnostics.js b/app/platform/linux/diagnostics.js index 3b9d5d5..b13f558 100644 --- a/app/platform/linux/diagnostics.js +++ b/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 }; diff --git a/docs/GETTING_STARTED_WITH_LINUX.md b/docs/GETTING_STARTED_WITH_LINUX.md index 1128177..29d18df 100644 --- a/docs/GETTING_STARTED_WITH_LINUX.md +++ b/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 -**capturing a screenshot every few seconds** (timed capture). +By default on Wayland, StepForge cannot see your clicks, so it uses a **global +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 -the mouse devices by joining the `input` group: +If you want a screenshot **on every click**, you can grant StepForge read +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). -Verify it took effect: - -```bash -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. +It shows you the exact rule and asks for confirmation before installing. Under +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). +Re-log in (or replug a USB mouse) for it to apply. > **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 - you're in the `input` group. -4. **Timed capture** — the always-works fallback (a screenshot every N seconds) - when no click source is available. + position on Wayland. Used when `xinput` can't see clicks (i.e. Wayland) and + only if you opted into the least-privilege mouse rule + (`scripts/linux/enable-click-capture.sh`). +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, diff --git a/packaging/linux/common/60-stepforge-input.rules b/packaging/linux/common/60-stepforge-input.rules new file mode 100644 index 0000000..d60ae04 --- /dev/null +++ b/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" diff --git a/scripts/linux/enable-click-capture.sh b/scripts/linux/enable-click-capture.sh new file mode 100755 index 0000000..408d127 --- /dev/null +++ b/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 diff --git a/tests/unit/wayland-honesty.test.js b/tests/unit/wayland-honesty.test.js new file mode 100644 index 0000000..442faf6 --- /dev/null +++ b/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/); +});