pi-polkit 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.1] - 2026-11-04
+
+### Added
+
+- `polkit-shims.ts`: `su` stand-in. `su -c COMMAND [USER]` (also `-cCOMMAND`,
+  `--command COMMAND`, `--command=COMMAND`) becomes
+  `pkexec --keep-cwd --user USER sh -c COMMAND`, because a non-login `su`
+  keeps the working directory and runs its command through a shell. Every other
+  form is refused with status `64` and one line naming the alternative: `su`,
+  `su -`, `su -l` (login shell → `pkexec bash`), `-m`/`-p`/`-w` (pkexec
+  sanitizes the environment), `-s` (name the shell in the command), `-g`/`-G`
+  (pkexec cannot switch groups), `--pty` (no terminal), `-f` and
+  `--session-command`.
+- README scope statement: the extension covers elevation → polkit only;
+  ssh, gpg/pinentry, keyrings, database clients, `kinit` and disk encryption
+  are explicitly out of scope and need an askpass helper or a PTY.
+
+### Changed
+
+- README authorisation note: a desktop agent may reuse the password it already
+  holds, so a second command can run without a dialog; that cache belongs to
+  the agent and must not be relied on. `su -c … USER` authenticates an
+  administrator rather than `USER`, and runs the command with `sh -c`.
+
 ## [0.1.0] - 2026-11-01
 
 ### Added

package/README.md

@@ -1,10 +1,24 @@
 # pi-polkit
 
-Redirects `sudo` and `doas` to `pkexec` inside Pi, so authorisation
+Redirects `sudo`, `doas` and `su -c` to `pkexec` inside Pi, so authorisation
 goes through the desktop's polkit agent (KDE, GNOME, …) instead of a terminal
 the shell tools do not have. Applies to the `bash` tool and to `!` user
 commands; `sudo` in other terminals is unchanged.
 
+## Scope
+
+This extension covers one category: **elevation → polkit**. It exists because
+the `bash` tool has no terminal, so any program that reads a password from
+`/dev/tty` fails there. `sudo`, `doas` and `su -c` are that category, and they
+are routed to `pkexec`, which asks the desktop's polkit agent instead.
+
+Password prompts that are not polkit's business are out of scope: `ssh`,
+`ssh-add`, `gpg`/pinentry, keyrings (`secret-tool`, KWallet), database clients
+(`psql`, `mysql -p`, `redis-cli`), `kinit`, and disk encryption (`cryptsetup`,
+`fscrypt`, `gocryptfs`). They read the process's own terminal, so they need an
+askpass helper or a pseudo-terminal, not polkit; mixing them in would make this
+extension's boundary meaningless.
+
 ## Installation
 
 Install as a Pi package (published on npm):
@@ -35,14 +49,18 @@ pi -e ./pi-polkit
 | `sudo -n …`            | refused: pkexec has no non-interactive mode |
 | `sudo -i`, `-s`, `-b`  | refused, with the equivalent command        |
 | `sudoedit`, `visudo`   | refused, with the alternative               |
+| `su -c 'id'`           | dialog, then runs as root                   |
+| `su -c 'id' bob`       | as above, as `bob` (administrator password) |
+| `su`, `su -`, `su -l`  | refused: no interactive shell, no terminal  |
+| `su -m`, `-s`, `-g`, `-w`, `--pty` | refused, with the alternative   |
 | `pkexec …`             | passed through                              |
 
 Refused invocations exit with status 64 and one line naming the alternative.
 
 ## How it works
 
-`sudo` and `doas` stand-ins are placed first on `PATH`, so the shell resolves
-those instead of the system binaries, and they forward the command to
+`sudo`, `doas` and `su` stand-ins are placed first on `PATH`, so the shell
+resolves those instead of the system binaries, and they forward the command to
 `pkexec`. Command text is never rewritten, so quoting, pipes and subshells need
 no special handling.
 
@@ -63,11 +81,21 @@ The shim directory is created lazily in `$XDG_RUNTIME_DIR` (falling back to
 one; other actions may not, according to policy. The extension takes no part in
 that decision.
 
+`org.freedesktop.policykit.exec` asks for administrator authentication on every
+call, but the desktop agent may keep the password it just received and answer
+the next challenge itself (KDE's agent does). A second command in the same
+session then runs without a dialog. That cache belongs to the agent: another
+agent, a restarted agent or a dismissed dialog means the next command prompts
+again, so do not rely on it.
+
 ## Limitations
 
 - Absolute paths (`/usr/bin/sudo`) and relative ones (`./sudo`) bypass `PATH`.
 - Commands that reset `PATH` (`env -i`, `PATH=/usr/bin …`) bypass it as well.
 - Programs that invoke `sudo` with a scrubbed environment bypass it.
+- `su -c … USER` authenticates an administrator (polkit), not `USER`, so an
+  account that real `su` would allow can be refused here.
+- `su -c` runs the command with `sh -c`, not with the target user's login shell.
 - PowerShell is not handled; the extension targets Linux only.
 
 These bypass the redirect, not polkit, which still decides whether the command

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-polkit",
-  "version": "0.1.0",
-  "description": "Redirect sudo/doas to pkexec in Pi via PATH shims, so the desktop polkit agent handles authentication",
+  "version": "0.1.1",
+  "description": "Redirect sudo, doas and su to pkexec in Pi via PATH shims, so the desktop polkit agent handles authentication",
   "type": "module",
   "pi": {
     "extensions": ["./index.ts"]
@@ -27,7 +27,7 @@
   "engines": {
     "node": ">=22.19.0"
   },
-  "keywords": ["pi-package", "pi-extension", "sudo", "doas", "pkexec", "polkit", "security"],
+  "keywords": ["pi-package", "pi-extension", "sudo", "doas", "su", "pkexec", "polkit", "security"],
   "license": "MIT",
   "repository": {
     "type": "git",

package/polkit-redirect.ts

@@ -3,13 +3,13 @@ import { createBashToolDefinition, createLocalBashOperations } from "@earendil-w
 import { polkitShimsPathExportLine, removePolkitShims, withPolkitShimsOnPath } from "./polkit-shims"
 
 /**
- * Redirects sudo and doas to pkexec inside Pi, so authorisation goes
+ * Redirects sudo, doas and su -c to pkexec inside Pi, so authorisation goes
  * through the desktop's polkit agent (KDE, GNOME, …) instead of a terminal the
  * shell tools do not have. Applies to the `bash` tool and to `!` user
  * commands; `sudo` in other terminals is unchanged.
  *
  * The redirect is a PATH prepend, not a command rewrite: the shims in
- * polkit-shims.ts stand in for the sudo/doas binaries, and the shell's own
+ * polkit-shims.ts stand in for the sudo/doas/su binaries, and the shell's own
  * name resolution picks them up for `sudo`, `$(sudo …)`, `xargs sudo`,
  * `FOO=1 sudo` and nested scripts alike. Nothing parses the command string,
  * and nothing parses pkexec's output: the shims hand pkexec's exit status
@@ -32,7 +32,7 @@ export default function polkitRedirect(pi: ExtensionAPI): void {
 }
 
 /**
- * Local shell operations whose commands resolve sudo through the shims. The
+ * Local shell operations whose commands resolve sudo and su through the shims. The
  * `!` user commands run through pi's own bash backend with no prepared
  * environment, so the PATH prepend happens as the first command line; the
  * exit status and output of the command itself are unchanged.

package/polkit-shims.ts

@@ -174,6 +174,113 @@ fi
 run_pkexec "$@"
 `
 
+/**
+ * The su shim. `su -c` is the only form pkexec can express exactly: a command
+ * run as the target user through a shell, in the current directory. Every
+ * other form asks for a login shell, an environment, a shell binary, a group
+ * or a terminal, none of which pkexec can honour, so it is refused instead.
+ */
+const SU_SHIM = `#!/bin/sh
+# pi-polkit: su shim. Routes su -c to pkexec so polkit can authorize it.
+# Generated at extension startup; do not edit.
+
+fail() {
+	printf 'pi-polkit: %s\\n' "$1" >&2
+	exit ${SHIM_USAGE_EXIT}
+}
+
+command -v pkexec >/dev/null 2>&1 || fail 'pkexec is not installed; install polkit'
+
+user=
+cmd=
+has_cmd=
+while [ $# -gt 0 ]; do
+	case $1 in
+	--)
+		shift
+		break
+		;;
+	-c)
+		[ $# -ge 2 ] || fail 'su -c needs a command: su -c COMMAND [USER]'
+		cmd=$2
+		has_cmd=1
+		shift 2
+		;;
+	-c?*)
+		cmd=\${1#-c}
+		has_cmd=1
+		shift
+		;;
+	--command)
+		[ $# -ge 2 ] || fail 'su --command needs a command: su --command COMMAND [USER]'
+		cmd=$2
+		has_cmd=1
+		shift 2
+		;;
+	--command=*)
+		cmd=\${1#--command=}
+		has_cmd=1
+		shift
+		;;
+	- | -l | --login)
+		fail 'su starts a login shell; run pkexec bash instead.'
+		;;
+	-s | --shell | -s?* | --shell=*)
+		fail 'su -s picks the shell; name the shell in the command: pkexec sh -c ...'
+		;;
+	-m | -p | --preserve-environment)
+		fail 'pkexec deliberately sanitizes the environment; drop -m/-p.'
+		;;
+	-g | -G | --group | --supp-group | -g?* | -G?* | --group=* | --supp-group=*)
+		fail 'su -g/-G switches groups; pkexec can only switch users.'
+		;;
+	-w | --whitelist-environment | -w?* | --whitelist-environment=*)
+		fail 'su -w whitelists environment variables; pkexec sanitizes the environment.'
+		;;
+	-P | --pty)
+		fail 'su --pty asks for a terminal; the bash tool has none.'
+		;;
+	-f | --fast)
+		fail 'su -f is a shell flag; pass it to the shell in the command instead.'
+		;;
+	--session-command | --session-command=*)
+		fail 'su --session-command keeps the session; pkexec always starts a new process.'
+		;;
+	-h | --help | -V | --version)
+		fail "option has no pkexec equivalent: $1"
+		;;
+	-?*)
+		fail "unknown su option: $1"
+		;;
+	*)
+		[ -z "$user" ] || fail 'su passes arguments after the user name to the shell; use su -c COMMAND USER.'
+		user=$1
+		shift
+		;;
+	esac
+done
+
+# Operands after -- are the same user-then-nothing sequence.
+while [ $# -gt 0 ]; do
+	[ -z "$user" ] || fail 'su passes arguments after the user name to the shell; use su -c COMMAND USER.'
+	user=$1
+	shift
+done
+
+[ -n "$user" ] || user=root
+[ -n "$has_cmd" ] || fail 'su without -c opens an interactive shell; run pkexec bash instead.'
+
+# su keeps the working directory unless it is a login shell, and --keep-cwd is
+# how pkexec does the same. pkexec is silent when the dialog is dismissed
+# (status 126), so say what the status means.
+pkexec --keep-cwd --user "$user" sh -c "$cmd"
+status=$?
+if [ $status -eq 126 ]; then
+	printf 'pi-polkit: %s\\n' 'the polkit authentication dialog was dismissed' >&2
+fi
+exit $status
+`
+
 /** sudoedit edits through sudo's own temporary-file flow; polkit has none. */
 const SUDOEDIT_SHIM = `#!/bin/sh
 printf 'pi-polkit: sudoedit is not supported; write a temp file and run pkexec install or pkexec cp on it.\\n' >&2
@@ -190,6 +297,7 @@ exit ${SHIM_USAGE_EXIT}
 const POLKIT_SHIM_SCRIPTS: Record<string, string> = {
   sudo: SUDO_SHIM,
   doas: DOAS_SHIM,
+  su: SU_SHIM,
   sudoedit: SUDOEDIT_SHIM,
   visudo: VISUDO_SHIM,
 }
@@ -198,8 +306,8 @@ const POLKIT_SHIM_SCRIPTS: Record<string, string> = {
 let shimDirectory: string | undefined
 
 /**
- * Returns the shim directory, writing the sudo/doas stand-in scripts on first
- * use. Creation is lazy so factory-only invocations (runs that never start a
+ * Returns the shim directory, writing the stand-in scripts on first use.
+ * Creation is lazy so factory-only invocations (runs that never start a
  * session) leave nothing behind.
  */
 export function ensurePolkitShims(): string {
@@ -219,7 +327,7 @@ export function removePolkitShims(): void {
 
 /**
  * Returns the environment with the shim directory first on PATH, so the shell
- * resolves sudo and doas to the shims instead of the system binaries. The
+ * resolves sudo, doas and su to the shims instead of the system binaries. The
  * prepend is idempotent: an environment that already carries the prefix is
  * returned unchanged.
  */