pi-polkit 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -5,6 +5,86 @@ 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.1] - 2026-11-07
+
+### Added
+
+- `test/polkit-shims.test.ts`: behaviour tests for the generated shims. They
+  stub `pkexec`, `pkcheck` and `pkaction` on `PATH`, so they need neither polkit,
+  a desktop agent nor root; `npm test` runs them with Node's test runner.
+- README: account-lockout section. Where the `polkit-1` PAM service includes
+  `pam_faillock`, a wrong or empty password submitted in the dialog adds a
+  record shared with terminal sudo and login; dismissing the dialog adds none,
+  an agent may allow several attempts in one dialog (each retry starts a new PAM
+  helper), and a locked account rejects even the correct password for
+  `unlock_time`. Documents how to inspect and reset the tally, and why retrying
+  does not help.
+- README limitation: `-n`, `-v` and `-l` check
+  `org.freedesktop.policykit.exec` itself, while pkexec may select another
+  action installed with `org.freedesktop.policykit.exec.path`/`argv1`
+  annotations.
+
+### Changed
+
+- The bash tool's prompt guideline now asks the model to consult the user before
+  retrying a dismissed or failed dialog, because failed or empty password
+  submissions count toward a system-wide `pam_faillock` lockout while a dismissal
+  does not.
+- README: `sudoers` and the `sudo` PAM stack are not consulted; polkit policy and
+  the `polkit-1` PAM service decide, so sudo-only modules such as a fingerprint
+  reader or a second factor do not run in Pi.
+- README now describes agent caching and retry behaviour generically instead of
+  attributing it to one desktop agent.
+- `sudo -v` reports an interactive failure as "polkit did not authorize" instead
+  of "polkit denies", since the check can fail after the password is rejected.
+
+## [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

package/README.md

@@ -1,9 +1,9 @@
 # pi-polkit
 
 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.
+goes through the desktop's polkit agent 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
 
@@ -46,8 +46,16 @@ 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`              | authenticates through polkit; creates no timestamp |
+| `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) |
@@ -55,7 +63,9 @@ pi -e ./pi-polkit
 | `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
 
@@ -73,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
 
@@ -81,12 +93,66 @@ 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.
 
+`sudoers` is not consulted: polkit policy decides who may run what, so per-user
+and per-command rules, `NOPASSWD`, `secure_path` and `env_keep` do not apply.
+Authentication runs through the `polkit-1` PAM service, not `/etc/pam.d/sudo`,
+so a module configured only for sudo — a fingerprint reader, a second factor —
+is not used here; the service's own stack (normally `system-auth`) decides how
+the password is verified.
+
 `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.
+call, but an agent may keep the password it just received and answer a later
+challenge itself. In that case a second command can run without a dialog. That
+cache belongs to the agent: a different agent, a restarted agent or a change in
+the agent's state can mean the next command prompts again, so do not rely on it.
+
+With the default policy, polkit records no temporary authorization for this
+action: after a successful `pkexec`, `pkcheck --list-temp` stays empty and a
+non-interactive `pkcheck` still reports that authentication is required. Whether
+a later command prompts is therefore the agent's decision, 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.
+
+The extension keeps no authorization state of its own: `sudo -v` verifies once
+and writes nothing, `sudo -n` assumes nothing, and `sudo -k` only clears polkit's
+record. Authorising one command therefore leaves the next one to be decided
+again, which is the point — the person who allowed an upgrade can still refuse
+the deletion that follows. What widens that window is the agent's password
+cache, not this extension, and nothing here can revoke it.
+
+## Account lockout
+
+When the `polkit-1` PAM service includes `pam_faillock` (Arch's default stack
+does), the dialog shares one failure tally per user with terminal sudo, `su` and
+the login screen:
+
+- A wrong or empty password submitted in the dialog adds a record. Dismissing
+  the dialog, closing it or pressing Esc cancels the agent's helper before PAM
+  returns, and adds none. (An agent process that is killed instead of
+  cancelling leaves the helper at EOF, and that attempt can count.)
+- An agent may allow several attempts in one dialog, and each retry starts a
+  new PAM helper; a dialog can therefore add several records and use up the
+  default `deny=3`.
+- Once a user has `deny` failures within `fail_interval` (900 s by default),
+  `pam_faillock` refuses that user in every service using the stack for
+  `unlock_time` (600 s by default, measured from the newest record). A locked
+  account rejects even the correct password, because `preauth` fails and
+  `authsucc` cannot reset the tally; further attempts neither extend nor shorten
+  the lock. A successful password authentication outside a lock resets the
+  tally.
+- `sudo -k` clears polkit's authorizations, not the tally. The locked user's own
+  authentication cannot succeed, so Pi cannot elevate with that user's
+  credentials to reset it: wait for the lock to expire, use a root console or
+  another administrator, or reboot (`/run` is cleared). Where the tally file is
+  readable by the user, `faillock --user "$USER"` shows the records and
+  `faillock --user "$USER" --reset` clears them without root; otherwise both
+  need root. Check readability with `ls -l /run/faillock/$USER`.
+
+Retrying a failed dialog in a loop only gives the user more chances to submit a
+wrong or empty password, and the lock applies to the whole account. The prompt
+guideline therefore tells the model to ask before retrying, and `sudo -n` remains
+the probe that never invokes PAM.
 
 ## Limitations
 
@@ -96,6 +162,15 @@ again, so do not rely on 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.
+- `-n`, `-v` and `-l` check `org.freedesktop.policykit.exec` itself. pkexec may
+  select a different action installed with an
+  `org.freedesktop.policykit.exec.path` (and `argv1`) annotation, so that
+  action's rules are not reflected by these checks.
+- `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
@@ -108,19 +183,21 @@ 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, denies it, or authentication failed |
+| 126    | the polkit dialog was dismissed                        |
+| 127    | not authorized (including after failed authentication), or the program could not run |
+| 64     | the extension refused the invocation                   |
 
 Messages are in English.
 
 ## Development
 
-`npm install && npm run check` type-checks against the pinned
-`@earendil-works/pi-coding-agent` 1.4.0, the API Pi serves to Node
-extensions.
+`npm install`, then `npm run check` type-checks against the pinned
+`@earendil-works/pi-coding-agent` 1.4.0, the API Pi serves to Node extensions,
+and `npm test` runs the shim behaviour tests. The tests stub `pkexec`, `pkcheck`
+and `pkaction` on `PATH`, so they need neither polkit, a desktop agent nor root.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-polkit",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Redirect sudo, doas and su to pkexec in Pi via PATH shims, so the desktop polkit agent handles authentication",
   "type": "module",
   "pi": {
@@ -14,7 +14,8 @@
   ],
   "scripts": {
     "check": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "npm run check"
+    "test": "node --experimental-strip-types --test test/*.test.ts",
+    "prepublishOnly": "npm run check && npm test"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"

package/polkit-redirect.ts

@@ -4,9 +4,9 @@ import { polkitShimsPathExportLine, removePolkitShims, withPolkitShimsOnPath } f
 
 /**
  * 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.
+ * through the desktop's polkit agent 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/su binaries, and the shell's own
@@ -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 a real authentication, and `sudo -l` prints the polkit policy that decides. Ask the user before retrying a dismissed or failed dialog instead of looping: on systems with pam_faillock, failed or empty password submissions count toward a system-wide lockout shared with login, while dismissing the dialog does not.",
   )
+  pi.registerTool(bash)
 
   pi.on("user_bash", () => ({ operations: polkitShimsUserBashOperations() }))
 

package/polkit-shims.ts

@@ -10,103 +10,412 @@ 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
 		;;
-	-v | --validate | -k | --reset-timestamp | -K | --remove-timestamp)
-		fail 'sudo credential caching does not exist under polkit; drop -v/-k.'
+	--set-home | --no-update | --preserve-groups)
+		shift
 		;;
-	-l | --list)
-		fail 'sudo -l is not available under polkit; inspect policy with pkaction --verbose.'
+	--list)
+		mode=list
+		shift
 		;;
-	-e | --edit)
-		fail 'sudoedit is not supported; write a temp file and run pkexec install or pkexec cp on it.'
+	--validate)
+		mode=validate
+		shift
 		;;
-	-i | --login | -s | --shell)
-		fail 'sudo -i/-s opens a login shell; run pkexec bash instead.'
+	--reset-timestamp | --remove-timestamp)
+		mode=revoke
+		shift
 		;;
-	-S | --stdin)
-		fail 'sudo -S reads the password from stdin; pkexec authenticates through the polkit agent. Drop -S.'
+	--background)
+		background=1
+		shift
 		;;
-	-A | --askpass)
-		fail 'SUDO_ASKPASS does not apply to pkexec; drop -A.'
+	--help)
+		mode=help
+		shift
 		;;
-	-b | --background)
-		fail 'sudo -b backgrounds the command; append & instead.'
+	--version)
+		mode=version
+		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.'
+	--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
+		;;
+	--shell)
+		mode=shell
+		shift
 		;;
-	-?*)
+	--*)
 		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
 		;;
 	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 did not authorize %s (the policy denies it, or authentication failed)\\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,20 +466,18 @@ 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 "$@"
 `
 
@@ -184,13 +491,9 @@ 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'
-
+${SHIM_PRELUDE}
+${SHIM_CHECKS}
+PROG=su
 user=
 cmd=
 has_cmd=
@@ -271,26 +574,72 @@ done
 [ -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
+# 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. */
@@ -300,6 +649,7 @@ const POLKIT_SHIM_SCRIPTS: Record<string, string> = {
   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. */