pi-polkit 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,77 @@ 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.2.0] - 2026-11-05
+
+### Added
+
+- `sudo -n`, `doas -n`: a non-interactive `pkcheck` on
+  `org.freedesktop.policykit.exec` decides whether the command runs. polkit grants
+  it without asking, or the shim exits `1` with `sudo: a password is required` and
+  the reason that dropping `-n` lets the agent answer. Measured: a successful
+  `pkexec` leaves no temporary authorization behind (`pkcheck --list-temp` stays
+  empty), so the silent second run is the agent's own password cache and no
+  non-interactive query can predict it; `-n` therefore reports policy, not a
+  guess.
+- `sudo -v` performs the authentication (`pkcheck --allow-user-interaction`) and
+  exits `0`, `1`, `126` when the dialog is dismissed, or `127`; `sudo -nv` uses
+  the non-interactive check.
+- `sudo -l` prints `pkaction --verbose` for the action and this session's
+  temporary authorizations.
+- `sudo -k`/`-K` revoke polkit's temporary authorizations and say that an agent's
+  own password cache cannot be cleared from here.
+- `sudo -H`, `-N`, `-P` are accepted as no-ops: pkexec already sets `HOME`, keeps
+  no timestamp and leaves groups alone.
+- `sudo -s COMMAND` and `--shell` run the command through a shell, `sudo -b`
+  starts it in the background and returns, and `sudo -E`/
+  `--preserve-env[=LIST]` re-export the environment inside the command.
+- `sudo --help` and `sudo -V` are answered by the real binary, so scripts that
+  probe sudo keep working.
+- Short options bundle (`sudo -nu bob`), and unknown long options report their own
+  name instead of `--`.
+- Registered bash tool: one guideline line tells the model that elevation goes
+  through polkit, what `-n`, `-v` and `-l` answer, so it plans with the real
+  contract instead of learning it from a failed call.
+- `pi-polkit-env`: helper that turns `NAME=VALUE` arguments into export
+  statements. `-E` passes entries through argv (`env -0` into `xargs -0`), so
+  spaces, quotes and newlines survive, and it drops every shim directory from
+  `PATH` so an elevated command cannot resolve sudo back to a shim.
+
+### Changed
+
+- The shims share one prologue: `fail`, the polkit subject (pinned with
+  `pid,start-time,uid` as `pkcheck(1)` requires), the two checks and the `pkexec`
+  wrapper.
+- `-n` failures exit `1` like sudo, not `64`: `64` now means only that the
+  invocation cannot be expressed. README documents the four-way handling
+  (translated, no-op, checked, refused) and polkit's missing temp authorization.
+- `sudo -i`, `-S`, `-A`, `sudoedit` and `visudo` still refuse, now from the shared
+  prelude.
+
+## [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):
@@ -32,17 +46,31 @@ pi -e ./pi-polkit
 | `sudo apt install x`   | polkit dialog, then runs as root            |
 | `sudo -u bob …`        | as above, as `bob`                          |
 | `cat x \| sudo tee y`  | dialog for `tee`                            |
-| `sudo -n …`            | refused: pkexec has no non-interactive mode |
-| `sudo -i`, `-s`, `-b`  | refused, with the equivalent command        |
+| `sudo -n …`            | runs only if polkit would authorise without asking; otherwise exit 1 with `sudo: a password is required` |
+| `sudo -v`              | performs the authentication, as `sudo -v` does |
+| `sudo -l`              | prints the polkit policy and this session's temporary authorizations |
+| `sudo -k`, `-K`        | revokes polkit's temporary authorizations   |
+| `sudo -H`, `-N`, `-P`  | accepted: pkexec already does what they ask |
+| `sudo -s CMD`          | runs `CMD` through a shell, as root         |
+| `sudo -E …`            | runs with the caller's environment          |
+| `sudo -b …`            | starts the command in the background        |
+| `sudo --help`, `-V`    | answered by the real sudo; nothing elevates |
+| `sudo -i`, `-S`, `-A`  | 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.
+An option is refused only when polkit cannot express it: it needs a terminal, a
+password channel polkit does not have, or an editor. Refusals 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.
 
@@ -55,7 +83,9 @@ Two wiring paths put the stand-ins on `PATH`, one per execution form:
   line instead.
 
 The shim directory is created lazily in `$XDG_RUNTIME_DIR` (falling back to
-`/tmp`) as `0700` and removed at session shutdown.
+`/tmp`) as `0700` and removed at session shutdown. It also holds
+`pi-polkit-env`, the helper that `sudo -E` uses to re-export an environment
+pkexec stripped.
 
 ## Authorisation
 
@@ -63,11 +93,34 @@ 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.
+
+Measured on polkit 128 with `polkit-gnome`'s agent: after a successful `pkexec`,
+`pkcheck --list-temp` prints nothing and a non-interactive `pkcheck` still
+reports that authentication is required. polkit records no temporary
+authorization for this action, so the silent second run is the agent answering
+from its own copy of the password, and no user-space query can predict it. That
+is why `sudo -n` reports what the policy says rather than guessing whether a
+dialog would appear, and why `sudo -k` can only clear polkit's own record.
+
 ## 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.
+- `sudo -E` re-exports the environment through `pkexec`'s argument list, so the
+  values are visible in `ps` while the command starts. Exported shell functions
+  are skipped, and `PATH` loses the shim directories.
+- `sudo -k` cannot clear the password a desktop agent holds; only polkit's
+  temporary authorizations are revoked.
 - PowerShell is not handled; the extension targets Linux only.
 
 These bypass the redirect, not polkit, which still decides whether the command
@@ -80,11 +133,12 @@ without one, `pkexec` fails instead of prompting.
 
 ## Exit status
 
-| Status | Meaning                                      |
-|--------|----------------------------------------------|
-| 126    | the polkit dialog was dismissed              |
-| 127    | not authorized, or the program could not run |
-| 64     | the extension refused the invocation         |
+| Status | Meaning                                                |
+|--------|--------------------------------------------------------|
+| 1      | `-n` or `-v` could not be satisfied: polkit requires authentication, or refuses |
+| 126    | the polkit dialog was dismissed                        |
+| 127    | not authorized, or the program could not run           |
+| 64     | the extension refused the invocation                   |
 
 Messages are in English.
 

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.2.0",
+  "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
@@ -19,11 +19,15 @@ export default function polkitRedirect(pi: ExtensionAPI): void {
   // The bash tool spawns with a prepared environment, so the shims reach it as
   // a PATH prepend. Registering the built-in's own definition under its own
   // name replaces it and keeps its prompt metadata and renderers.
-  pi.registerTool(
-    createBashToolDefinition(process.cwd(), {
-      spawnHook: ({ command, cwd, env }) => ({ command, cwd, env: withPolkitShimsOnPath(env) }),
-    }),
+  const bash = createBashToolDefinition(process.cwd(), {
+    spawnHook: ({ command, cwd, env }) => ({ command, cwd, env: withPolkitShimsOnPath(env) }),
+  })
+  // The model plans privilege with what it knows about sudo. Say once, in the
+  // system prompt, how this shell differs, so it does not learn it by failing.
+  bash.promptGuidelines?.push(
+    "`sudo`, `doas` and `su -c` are routed to pkexec, so a desktop polkit dialog authorises them instead of a terminal password prompt. `sudo -n` runs the command only if polkit would authorise it without asking, `sudo -v` performs the authentication, and `sudo -l` prints the polkit policy that decides.",
   )
+  pi.registerTool(bash)
 
   pi.on("user_bash", () => ({ operations: polkitShimsUserBashOperations() }))
 
@@ -32,7 +36,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

@@ -10,82 +10,263 @@ import { isAbsolute, join } from "node:path"
  */
 export const SHIM_USAGE_EXIT = 64
 
+/** The action pkexec checks; the checks below ask polkit about the same one. */
+const POLKIT_ACTION = "org.freedesktop.policykit.exec"
+
 /**
- * The sudo shim. Lives on PATH ahead of the real sudo, so the shell — not
- * this extension — decides that `sudo` means this file. It forwards to pkexec
- * and never parses what pkexec prints: the exit status is the whole result.
- *
- * Only options with an exact pkexec equivalent are translated. Everything
- * else is refused with an actionable message rather than forwarded, because
- * pkexec would reject it with a message that does not say what to do instead.
+ * The part every shim starts with: one refusal helper, and a check that the two
+ * polkit tools exist at all.
  */
-const SUDO_SHIM = `#!/bin/sh
-# pi-polkit: sudo shim. Routes sudo to pkexec so polkit can authorize it.
-# Generated at extension startup; do not edit.
-
-fail() {
+const SHIM_PRELUDE = `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'
+command -v pkcheck >/dev/null 2>&1 || fail 'pkcheck is not installed; install polkit'
+`
+
+/**
+ * The checks that answer what sudo's timestamp file used to answer, plus the
+ * pkexec wrapper. Only exit statuses are read: pkcheck's messages and its
+ * `polkit.result` detail are localised and addressed to humans, so parsing them
+ * would break on the next locale or polkit release.
+ */
+const SHIM_CHECKS = `# The action pkexec checks: a pkcheck verdict on it describes what the next
+# pkexec will do, which is how the shims answer what sudo's timestamp answered.
+ACTION=${POLKIT_ACTION}
+
+# pkcheck(1) warns that a bare pid races with pid reuse, so pin the start time.
+subject() {
+	started=$(awk '{ print $22 }' /proc/$$/stat 2>/dev/null)
+	if [ -n "$started" ]; then
+		printf '%s,%s,%s' "$$" "$started" "$(id -u)"
+	else
+		printf '%s' "$$"
+	fi
+}
+
+# 0 grants the action without asking anyone, 2 requires authentication,
+# 1 refuses it. pkcheck's own 126 (usage) and 127 (error) pass through.
+check_without_prompt() {
+	pkcheck --action-id "$ACTION" --process "$(subject)" >/dev/null 2>&1
+}
+
+# The same check with the desktop agent allowed to answer. An agent that still
+# holds the password answers without a dialog, which is why a 0 here also means
+# the next pkexec runs as root without asking.
+check_with_prompt() {
+	pkcheck --action-id "$ACTION" --process "$(subject)" --allow-user-interaction >/dev/null 2>&1
+}
+
+# -n means "run only if no one has to be asked". polkit cannot say whether the
+# agent would answer from its cache, so a 2 is reported as needing a password
+# and the command is not run: that is what -n promises, in both directions.
+require_without_prompt() {
+	if [ -n "$noninteractive" ]; then
+		check_without_prompt
+		status=$?
+		case $status in
+		0)
+			return 0
+			;;
+		1)
+			printf 'pi-polkit: %s: polkit denies %s to this process\\n' "$PROG" "$ACTION" >&2
+			exit 1
+			;;
+		2)
+			printf '%s: a password is required (polkit requires authentication for %s; drop -n to let the desktop agent answer, which it may do from its cache)\\n' "$PROG" "$ACTION" >&2
+			exit 1
+			;;
+		*)
+			printf 'pi-polkit: %s: polkit check failed (status %s)\\n' "$PROG" "$status" >&2
+			exit 127
+			;;
+		esac
+	fi
+	return 0
+}
+
+# pkexec is silent when the dialog is dismissed (status 126), so say what the
+# status means. Every other failure path already prints its own reason.
+run_pkexec() {
+	pkexec "$@"
+	status=$?
+	if [ $status -eq 126 ]; then
+		printf 'pi-polkit: %s\\n' 'the polkit authentication dialog was dismissed' >&2
+	fi
+	exit $status
+}
+`
+
+/**
+ * The sudo shim. Lives on PATH ahead of the real sudo, so the shell — not this
+ * extension — decides that `sudo` means this file. It forwards to pkexec and
+ * never parses what pkexec prints: the exit status is the whole result.
+ *
+ * Options are handled in four ways, and only the last one refuses. Those whose
+ * effect pkexec already has (`-H`, `-N`, `-P`) are accepted as no-ops; those
+ * polkit answers better than a run (`-n`, `-v`, `-l`, `-k`) become checks; those
+ * a wrapper can express (`-s COMMAND`, `-E`, `-b`) are translated; the rest,
+ * which need a terminal or a password channel polkit does not have, are refused
+ * with one line naming the alternative.
+ */
+const SUDO_SHIM = `#!/bin/sh
+# pi-polkit: sudo shim. Routes sudo to pkexec so polkit can authorize it.
+# Generated at extension startup; do not edit.
 
+${SHIM_PRELUDE}
+${SHIM_CHECKS}
+PROG=sudo
 user=
+noninteractive=
+preserve=
+preserve_names=
+background=
+mode=
+
 while [ $# -gt 0 ]; do
 	case $1 in
 	--)
 		shift
 		break
 		;;
-	-u)
-		[ $# -ge 2 ] || fail 'sudo -u needs a username: -u USER PROGRAM'
-		user=$2
-		shift 2
-		;;
 	--user)
 		[ $# -ge 2 ] || fail 'sudo --user needs a username: --user USER PROGRAM'
 		user=$2
 		shift 2
 		;;
-	-u?*)
-		user=\${1#-u}
-		[ -n "$user" ] || fail 'sudo -u needs a username: -u USER PROGRAM'
-		shift
-		;;
 	--user=*)
 		user=\${1#--user=}
-		[ -n "$user" ] || fail 'sudo --user needs a username: --user USER PROGRAM'
 		shift
 		;;
-	-n | --non-interactive)
-		fail 'sudo -n is not supported: pkexec has no non-interactive mode, polkit decides whether authentication is needed. Drop -n.'
+	--non-interactive)
+		noninteractive=1
+		shift
+		;;
+	--preserve-env)
+		preserve=1
+		shift
+		;;
+	--preserve-env=*)
+		preserve=1
+		preserve_names=\${1#--preserve-env=}
+		shift
+		;;
+	--set-home | --no-update | --preserve-groups)
+		shift
+		;;
+	--list)
+		mode=list
+		shift
 		;;
-	-v | --validate | -k | --reset-timestamp | -K | --remove-timestamp)
-		fail 'sudo credential caching does not exist under polkit; drop -v/-k.'
+	--validate)
+		mode=validate
+		shift
 		;;
-	-l | --list)
-		fail 'sudo -l is not available under polkit; inspect policy with pkaction --verbose.'
+	--reset-timestamp | --remove-timestamp)
+		mode=revoke
+		shift
 		;;
-	-e | --edit)
-		fail 'sudoedit is not supported; write a temp file and run pkexec install or pkexec cp on it.'
+	--background)
+		background=1
+		shift
 		;;
-	-i | --login | -s | --shell)
-		fail 'sudo -i/-s opens a login shell; run pkexec bash instead.'
+	--help)
+		mode=help
+		shift
 		;;
-	-S | --stdin)
-		fail 'sudo -S reads the password from stdin; pkexec authenticates through the polkit agent. Drop -S.'
+	--version)
+		mode=version
+		shift
 		;;
-	-A | --askpass)
-		fail 'SUDO_ASKPASS does not apply to pkexec; drop -A.'
+	--stdin | --askpass | --edit | --login)
+		case $1 in
+		--edit)
+			fail 'sudoedit is not supported; write a temp file and run pkexec install or pkexec cp on it.'
+			;;
+		--stdin)
+			fail 'sudo -S reads the password from stdin; pkexec authenticates through the polkit agent. Drop -S.'
+			;;
+		--askpass)
+			fail 'SUDO_ASKPASS does not apply to pkexec; drop -A.'
+			;;
+		*)
+			fail 'sudo -i opens a login shell; run pkexec bash instead.'
+			;;
+		esac
 		;;
-	-b | --background)
-		fail 'sudo -b backgrounds the command; append & instead.'
+	--shell)
+		mode=shell
+		shift
 		;;
-	-E | --preserve-env | --preserve-env=* | -H | --set-home | -P | --preserve-groups | -N | --no-update)
-		fail 'pkexec deliberately sanitizes the environment; drop -E/-H/-P.'
+	--*)
+		fail "option has no pkexec equivalent: $1 (pkexec accepts --user, --keep-cwd, --disable-internal-agent)"
 		;;
 	-?*)
-		fail "option has no pkexec equivalent: $1 (pkexec accepts --user, --keep-cwd, --disable-internal-agent)"
+		rest=\${1#-}
+		shift
+		while [ -n "$rest" ]; do
+			letter=\${rest%"\${rest#?}"}
+			rest=\${rest#?}
+			case $letter in
+			u)
+				if [ -n "$rest" ]; then
+					user=$rest
+					rest=
+				else
+					[ $# -ge 1 ] || fail 'sudo -u needs a username: -u USER PROGRAM'
+					user=$1
+					shift
+				fi
+				;;
+			n)
+				noninteractive=1
+				;;
+			E)
+				preserve=1
+				;;
+			H | N | P)
+				# pkexec already sets HOME, keeps no timestamp and leaves groups alone.
+				;;
+			b)
+				background=1
+				;;
+			l)
+				mode=list
+				;;
+			v)
+				mode=validate
+				;;
+			k | K)
+				mode=revoke
+				;;
+			s)
+				mode=shell
+				;;
+			h)
+				mode=help
+				;;
+			V)
+				mode=version
+				;;
+			i)
+				fail 'sudo -i opens a login shell; run pkexec bash instead.'
+				;;
+			e)
+				fail 'sudoedit is not supported; write a temp file and run pkexec install or pkexec cp on it.'
+				;;
+			S)
+				fail 'sudo -S reads the password from stdin; pkexec authenticates through the polkit agent. Drop -S.'
+				;;
+			A)
+				fail 'SUDO_ASKPASS does not apply to pkexec; drop -A.'
+				;;
+			*)
+				fail "option has no pkexec equivalent: -$letter (pkexec accepts --user, --keep-cwd, --disable-internal-agent)"
+				;;
+			esac
+		done
 		;;
 	*)
 		break
@@ -93,20 +274,148 @@ while [ $# -gt 0 ]; do
 	esac
 done
 
-# pkexec is silent when the dialog is dismissed (status 126), so say what the
-# status means. Every other failure path already prints its own reason.
-run_pkexec() {
-	pkexec "$@"
+# --help and --version describe the binary, not the authorisation, so nothing is
+# elevated: answering them exactly keeps scripts that probe sudo working.
+if [ "$mode" = help ] || [ "$mode" = version ]; then
+	for candidate in /usr/bin/sudo /bin/sudo /usr/local/bin/sudo; do
+		[ -x "$candidate" ] || continue
+		if [ "$mode" = help ]; then
+			exec "$candidate" --help
+		fi
+		exec "$candidate" --version
+	done
+	fail 'the real sudo is not installed, so --help and --version cannot be answered'
+fi
+
+# -l reports the policy polkit will apply and the authorizations this session
+# already holds. Both halves are local and never prompt.
+if [ "$mode" = list ]; then
+	pkaction --action-id "$ACTION" --verbose || exit 127
+	printf '\\npi-polkit: temporary authorizations in this session\\n'
+	pkcheck --list-temp || exit 127
+	exit 0
+fi
+
+# -v asks the same question sudo -v asks: can authentication succeed right now?
+if [ "$mode" = validate ]; then
+	if [ -n "$noninteractive" ]; then
+		check_without_prompt
+	else
+		check_with_prompt
+	fi
 	status=$?
-	if [ $status -eq 126 ]; then
-		printf 'pi-polkit: %s\n' 'the polkit authentication dialog was dismissed' >&2
+	case $status in
+	0)
+		exit 0
+		;;
+	1)
+		printf 'pi-polkit: sudo: polkit denies %s to this process\\n' "$ACTION" >&2
+		exit 1
+		;;
+	2)
+		if [ -n "$noninteractive" ]; then
+			printf 'sudo: a password is required (polkit requires authentication for %s)\\n' "$ACTION" >&2
+		else
+			printf 'pi-polkit: sudo: no polkit authentication agent answered\\n' >&2
+		fi
+		exit 1
+		;;
+	3)
+		printf 'pi-polkit: %s\\n' 'the polkit authentication dialog was dismissed' >&2
+		exit 126
+		;;
+	*)
+		printf 'pi-polkit: sudo: polkit check failed (status %s)\\n' "$status" >&2
+		exit 127
+		;;
+	esac
+fi
+
+# -k drops what polkit itself recorded. The password a desktop agent keeps is
+# the agent's, not polkit's, so say that it stays.
+if [ "$mode" = revoke ]; then
+	pkcheck --revoke-temp || exit 127
+	if [ $# -eq 0 ]; then
+		printf 'pi-polkit: %s\\n' 'revoked the temporary polkit authorizations; a desktop agent that caches the password keeps its own copy, so the next command may still not ask' >&2
+		exit 0
 	fi
-	exit $status
+fi
+
+# -E: pkexec strips the environment, so name the variables again inside the shell
+# that runs the command. Entries reach the helper as arguments, so spaces, quotes
+# and newlines survive exactly; the helper also drops every shim directory from
+# PATH, so an elevated command cannot resolve sudo back to a shim.
+shim_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd 2>/dev/null)
+env_helper=$shim_dir/pi-polkit-env
+[ -x "$env_helper" ] || fail "the pi-polkit environment helper is missing: $env_helper"
+
+# Runs in the caller's shell, never in a command substitution: an exit there
+# would only end the subshell, and a name reaches eval below, so it must be a
+# name before that happens.
+check_preserve() {
+	if [ -z "$preserve_names" ]; then
+		command -v xargs >/dev/null 2>&1 || fail '-E needs xargs to forward the environment; name the variables instead: --preserve-env=NAME[,NAME...]'
+		return 0
+	fi
+	old_ifs=$IFS
+	IFS=,
+	for name in $preserve_names; do
+		case $name in
+		'' | [0-9]* | *[!A-Za-z0-9_]*)
+			IFS=$old_ifs
+			fail "not a variable name: $name"
+			;;
+		esac
+	done
+	IFS=$old_ifs
+}
+
+export_prefix() {
+	if [ -n "$preserve_names" ]; then
+		set --
+		old_ifs=$IFS
+		IFS=,
+		for name in $preserve_names; do
+			is_set=
+			eval "is_set=\\\${$name+yes}"
+			[ -n "$is_set" ] || continue
+			eval "value=\\\${$name}"
+			set -- "$@" "$name=$value"
+		done
+		IFS=$old_ifs
+		"$env_helper" "$@"
+		return
+	fi
+	env -0 | xargs -0 -n 64 "$env_helper"
 }
 
+require_without_prompt
+
+[ $# -gt 0 ] || fail 'sudo needs a command: sudo [OPTIONS] COMMAND (an interactive shell needs a terminal)'
+
+# -s runs the command through a shell, which pkexec expresses exactly.
+if [ "$mode" = shell ]; then
+	set -- /bin/sh -c "$*"
+fi
+
+# The preserved environment is exported by a shell prologue, so the command keeps
+# its own argv rather than being flattened into one string.
+if [ -n "$preserve" ]; then
+	check_preserve
+	prefix=$(export_prefix)
+	set -- /bin/sh -c "\${prefix}exec \\"\\$@\\"" sh "$@"
+fi
+
 if [ -n "$user" ]; then
-	run_pkexec --user "$user" "$@"
+	set -- --user "$user" "$@"
+fi
+
+# -b returns as soon as the command is started, as sudo -b does.
+if [ -n "$background" ]; then
+	pkexec "$@" &
+	exit 0
 fi
+
 run_pkexec "$@"
 `
 
@@ -115,14 +424,13 @@ const DOAS_SHIM = `#!/bin/sh
 # pi-polkit: doas shim. Routes doas 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'
-
+${SHIM_PRELUDE}
+${SHIM_CHECKS}
+PROG=doas
 user=
+noninteractive=
+mode=
+
 while [ $# -gt 0 ]; do
 	case $1 in
 	--)
@@ -136,14 +444,15 @@ while [ $# -gt 0 ]; do
 		;;
 	-u?*)
 		user=\${1#-u}
-		[ -n "$user" ] || fail 'doas -u needs a username: -u USER PROGRAM'
 		shift
 		;;
 	-n)
-		fail 'doas -n is not supported: pkexec has no non-interactive mode. Drop -n.'
+		noninteractive=1
+		shift
 		;;
 	-s)
-		fail 'doas -s opens a shell; run pkexec bash instead.'
+		mode=shell
+		shift
 		;;
 	-C | -a | -L)
 		fail "option has no pkexec equivalent: $1"
@@ -157,49 +466,198 @@ while [ $# -gt 0 ]; do
 	esac
 done
 
-# pkexec is silent when the dialog is dismissed (status 126), so say what the
-# status means. Every other failure path already prints its own reason.
-run_pkexec() {
-	pkexec "$@"
-	status=$?
-	if [ $status -eq 126 ]; then
-		printf 'pi-polkit: %s\n' 'the polkit authentication dialog was dismissed' >&2
-	fi
-	exit $status
-}
+require_without_prompt
+
+[ $# -gt 0 ] || fail 'doas needs a command: doas [OPTIONS] COMMAND (an interactive shell needs a terminal)'
+
+if [ "$mode" = shell ]; then
+	set -- /bin/sh -c "$*"
+fi
 
 if [ -n "$user" ]; then
-	run_pkexec --user "$user" "$@"
+	set -- --user "$user" "$@"
 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.
+
+${SHIM_PRELUDE}
+${SHIM_CHECKS}
+PROG=su
+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.
+run_pkexec --keep-cwd --user "$user" sh -c "$cmd"
+`
+
+/**
+ * The environment helper: turns `NAME=VALUE` arguments into an export statement
+ * each, so `-E` can rebuild the environment pkexec stripped. Values arrive as
+ * arguments rather than text, so spaces, quotes and newlines need no escaping on
+ * the way in. PATH keeps every entry except the shim directories.
+ */
+const POLKIT_ENV_HELPER = `#!/bin/sh
+# pi-polkit: rebuilds a stripped environment. Generated at extension startup;
+# do not edit.
+
+for entry in "$@"; do
+	name=\${entry%%=*}
+	value=\${entry#*=}
+	case $name in
+	'' | [0-9]* | *[!A-Za-z0-9_]*)
+		continue
+		;;
+	PATH)
+		filtered=
+		old_ifs=$IFS
+		IFS=:
+		for dir in $value; do
+			case \${dir##*/} in
+			pi-polkit-*)
+				continue
+				;;
+			esac
+			filtered=$filtered\${filtered:+:}$dir
+		done
+		IFS=$old_ifs
+		value=$filtered
+		;;
+	esac
+	quote="'"
+	quoted=
+	while :; do
+		case $value in
+		*"$quote"*)
+			quoted=$quoted\${value%%"$quote"*}"'\\\\''"
+			value=\${value#*"$quote"}
+			;;
+		*)
+			quoted=$quoted$value
+			break
+			;;
+		esac
+	done
+	printf "export '%s=%s'; " "$name" "$quoted"
+done
+`
+
+
 /** 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
-exit ${SHIM_USAGE_EXIT}
+${SHIM_PRELUDE}
+fail 'sudoedit is not supported; write a temp file and run pkexec install or pkexec cp on it.'
 `
 
 /** visudo needs an interactive editor on a terminal the shell tool does not have. */
 const VISUDO_SHIM = `#!/bin/sh
-printf 'pi-polkit: visudo needs an interactive terminal; validate a candidate file with pkexec visudo -c -f FILE instead.\\n' >&2
-exit ${SHIM_USAGE_EXIT}
+${SHIM_PRELUDE}
+fail 'visudo needs an interactive terminal; validate a candidate file with pkexec visudo -c -f FILE instead.'
 `
 
 /** File name → script body. Names must match the commands being redirected. */
 const POLKIT_SHIM_SCRIPTS: Record<string, string> = {
   sudo: SUDO_SHIM,
   doas: DOAS_SHIM,
+  su: SU_SHIM,
   sudoedit: SUDOEDIT_SHIM,
   visudo: VISUDO_SHIM,
+  "pi-polkit-env": POLKIT_ENV_HELPER,
 }
 
 /** Shim directory of the running extension; created on first use, cleared by removePolkitShims. */
 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 +677,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.
  */