opencode-polkit 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,53 @@ 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.4.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 `--`.
+- `opencode-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.
+- `src/index.ts`: the shell tool's description gains one sentence naming the
+  redirect and what `-n`, `-v` and `-l` answer, so the model plans privilege with
+  the real contract instead of learning it from a failed call.
+
+### 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.3.1] - 2026-11-04
 
 ### Added

package/README.md

@@ -48,8 +48,16 @@ For a local checkout, run `npm run build` once, then reference the directory:
 | `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) |
@@ -57,7 +65,9 @@ For a local checkout, run `npm run build` once, then reference the directory:
 | `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
 
@@ -66,6 +76,16 @@ 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.
 
+The `create.before` shell hook prepends the stand-in directory to the spawned
+`PATH`. The directory lives in `$XDG_RUNTIME_DIR` (falling back to `/tmp`) as
+`0700`, is removed when the plugin is unloaded, and also holds
+`opencode-polkit-env`, the helper `sudo -E` uses to re-export an environment
+pkexec stripped.
+
+The shell tool's description gains one sentence about the redirect, so the model
+plans privilege with the real contract instead of learning it from a failed
+call.
+
 ## Authorisation
 
 `polkitd` decides whether a password is required. These commands always require
@@ -79,6 +99,14 @@ 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`.
@@ -87,6 +115,11 @@ 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.
+- `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.
 
 These bypass the redirect, not polkit, which still decides whether the command
 runs.
@@ -98,11 +131,12 @@ without one, `pkexec` fails instead of prompting.
 
 ## Exit status
 
-| Status | Meaning                                      |
-|--------|----------------------------------------------|
-| 126    | the polkit dialog was dismissed              |
-| 127    | not authorised, or the program could not run |
-| 64     | the plugin 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 authorised, or the program could not run           |
+| 64     | the plugin refused the invocation                      |
 
 Messages are in English.
 

package/dist/index.js

@@ -4,6 +4,16 @@ import { installPolkitShims, removePolkitShims } from "./shims.js";
  * Only the prepend matters; the rest is a last-resort fallback.
  */
 const FALLBACK_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+/** Tool names whose description should name how elevation works here. */
+const SHELL_TOOLS = ["bash", "shell"];
+/** Opening words of the appended description; also the guard against appending twice. */
+const CONTRACT_MARKER = "polkit redirect:";
+/**
+ * Appended to the shell tool's description. The model plans privilege with what
+ * it knows about sudo, so the difference is stated where it reads the tool,
+ * instead of being learned from a failed call.
+ */
+const SHELL_TOOL_CONTRACT = `${CONTRACT_MARKER} \`sudo\`, \`doas\` and \`su -c\` run through 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.`;
 /**
  * Redirects sudo/doas/su -c to pkexec without touching the command text.
  *
@@ -26,6 +36,20 @@ const setup = async (ctx) => {
         if (!path.startsWith(prefix))
             event.env.PATH = prefix + path;
     });
+    // The shell tool is the host's, so its description is extended rather than
+    // replaced. Every reload runs this transform again, so a description that
+    // already carries the line is left alone.
+    await ctx.tool.transform((tools) => {
+        for (const tool of tools.list()) {
+            if (!SHELL_TOOLS.includes(tool.id) && !SHELL_TOOLS.includes(tool.name))
+                continue;
+            tools.update(tool.id, (entry) => {
+                if (entry.description.includes(CONTRACT_MARKER))
+                    return;
+                entry.description = `${entry.description}\n\n${SHELL_TOOL_CONTRACT}`;
+            });
+        }
+    });
     return () => removePolkitShims(shimDir);
 };
 /**

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAElE;;;GAGG;AACH,MAAM,aAAa,GAAG,8DAA8D,CAAA;AAEpF;;;;;;;;;;;;GAYG;AACH,MAAM,KAAK,GAAG,KAAK,EAAE,GAAmB,EAA2B,EAAE;IACnE,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAA;IACpC,MAAM,MAAM,GAAG,GAAG,OAAO,GAAG,CAAA;IAE5B,8EAA8E;IAC9E,MAAM,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC,KAAK,EAAE,EAAE;QAC9C,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,IAAI,aAAa,CAAA;QAC5C,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,IAAI,GAAG,MAAM,GAAG,IAAI,CAAA;IAC9D,CAAC,CAAC,CAAA;IAEF,OAAO,GAAG,EAAE,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAA;AACzC,CAAC,CAAA;AAED;;;GAGG;AACH,eAAe,EAAE,EAAE,EAAE,iBAAiB,EAAE,KAAK,EAA0B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAElE;;;GAGG;AACH,MAAM,aAAa,GAAG,8DAA8D,CAAA;AAEpF,yEAAyE;AACzE,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAErC,yFAAyF;AACzF,MAAM,eAAe,GAAG,kBAAkB,CAAA;AAE1C;;;;GAIG;AACH,MAAM,mBAAmB,GAAG,GAAG,eAAe,wTAAwT,CAAA;AAEtW;;;;;;;;;;;;GAYG;AACH,MAAM,KAAK,GAAG,KAAK,EAAE,GAAmB,EAA2B,EAAE;IACnE,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAA;IACpC,MAAM,MAAM,GAAG,GAAG,OAAO,GAAG,CAAA;IAE5B,8EAA8E;IAC9E,MAAM,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC,KAAK,EAAE,EAAE;QAC9C,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,IAAI,aAAa,CAAA;QAC5C,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,IAAI,GAAG,MAAM,GAAG,IAAI,CAAA;IAC9D,CAAC,CAAC,CAAA;IAEF,2EAA2E;IAC3E,0EAA0E;IAC1E,0CAA0C;IAC1C,MAAM,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;QACjC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;YAChC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,SAAQ;YAChF,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE;gBAC9B,IAAI,KAAK,CAAC,WAAW,CAAC,QAAQ,CAAC,eAAe,CAAC;oBAAE,OAAM;gBACvD,KAAK,CAAC,WAAW,GAAG,GAAG,KAAK,CAAC,WAAW,OAAO,mBAAmB,EAAE,CAAA;YACtE,CAAC,CAAC,CAAA;QACJ,CAAC;IACH,CAAC,CAAC,CAAA;IAEF,OAAO,GAAG,EAAE,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAA;AACzC,CAAC,CAAA;AAED;;;GAGG;AACH,eAAe,EAAE,EAAE,EAAE,iBAAiB,EAAE,KAAK,EAA0B,CAAA"}

package/dist/shims.d.ts

@@ -9,7 +9,9 @@ export declare const SHIM_USAGE_EXIT = 64;
  * Writes the shim scripts into a fresh private directory and returns it.
  * The caller prepends this directory to PATH; the shell then resolves
  * `sudo`/`doas`/`su` to these files instead of the system ones. The directory
- * is 0700 so no other local user can rewrite the scripts.
+ * is 0700 so no other local user can rewrite the scripts, and it holds
+ * `opencode-polkit-env`, the helper `sudo -E` uses to re-export an environment
+ * pkexec stripped.
  */
 export declare function installPolkitShims(): string;
 /** Deletes a directory created by installPolkitShims. */

package/dist/shims.js

@@ -8,82 +8,260 @@ import { isAbsolute, join } from "node:path";
  * any output.
  */
 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 plugin — 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
-# opencode-polkit: sudo shim. Routes sudo to pkexec so polkit can authorize it.
-# Generated at plugin startup; do not edit.
-
-fail() {
+const SHIM_PRELUDE = `fail() {
 	printf 'opencode-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 'opencode-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 'opencode-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 'opencode-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
+ * plugin — 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
+# opencode-polkit: sudo shim. Routes sudo to pkexec so polkit can authorize it.
+# Generated at plugin 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
 		;;
-	-v | --validate | -k | --reset-timestamp | -K | --remove-timestamp)
-		fail 'sudo credential caching does not exist under polkit; drop -v/-k.'
+	--list)
+		mode=list
+		shift
 		;;
-	-l | --list)
-		fail 'sudo -l is not available under polkit; inspect policy with pkaction --verbose.'
+	--validate)
+		mode=validate
+		shift
 		;;
-	-e | --edit)
-		fail 'sudoedit is not supported; write a temp file and run pkexec install or pkexec cp on it.'
+	--reset-timestamp | --remove-timestamp)
+		mode=revoke
+		shift
 		;;
-	-i | --login | -s | --shell)
-		fail 'sudo -i/-s opens a login shell; run pkexec bash instead.'
+	--background)
+		background=1
+		shift
 		;;
-	-S | --stdin)
-		fail 'sudo -S reads the password from stdin; pkexec authenticates through the polkit agent. Drop -S.'
+	--help)
+		mode=help
+		shift
 		;;
-	-A | --askpass)
-		fail 'SUDO_ASKPASS does not apply to pkexec; drop -A.'
+	--version)
+		mode=version
+		shift
 		;;
-	-b | --background)
-		fail 'sudo -b backgrounds the command; append & instead.'
+	--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
 		;;
-	-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
@@ -91,20 +269,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 '\\nopencode-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 'opencode-polkit: %s\n' 'the polkit authentication dialog was dismissed' >&2
+	case $status in
+	0)
+		exit 0
+		;;
+	1)
+		printf 'opencode-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 'opencode-polkit: sudo: no polkit authentication agent answered\\n' >&2
+		fi
+		exit 1
+		;;
+	3)
+		printf 'opencode-polkit: %s\\n' 'the polkit authentication dialog was dismissed' >&2
+		exit 126
+		;;
+	*)
+		printf 'opencode-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 'opencode-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/opencode-polkit-env
+[ -x "$env_helper" ] || fail "the opencode-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 "$@"
 `;
 /** The doas shim: same contract, doas option grammar. */
@@ -112,14 +418,13 @@ const DOAS_SHIM = `#!/bin/sh
 # opencode-polkit: doas shim. Routes doas to pkexec so polkit can authorize it.
 # Generated at plugin startup; do not edit.
 
-fail() {
-	printf 'opencode-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
 	--)
@@ -133,14 +438,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"
@@ -154,20 +460,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 'opencode-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 "$@"
 `;
 /**
@@ -180,13 +484,9 @@ const SU_SHIM = `#!/bin/sh
 # opencode-polkit: su shim. Routes su -c to pkexec so polkit can authorize it.
 # Generated at plugin startup; do not edit.
 
-fail() {
-	printf 'opencode-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=
@@ -234,7 +534,7 @@ while [ $# -gt 0 ]; do
 		fail 'su -w whitelists environment variables; pkexec sanitizes the environment.'
 		;;
 	-P | --pty)
-		fail 'su --pty asks for a terminal; the shell tool has none.'
+		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.'
@@ -267,24 +567,68 @@ 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 'opencode-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
+# opencode-polkit: rebuilds a stripped environment. Generated at plugin 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
+			opencode-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 'opencode-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 'opencode-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 = {
@@ -293,12 +637,15 @@ const POLKIT_SHIM_SCRIPTS = {
     su: SU_SHIM,
     sudoedit: SUDOEDIT_SHIM,
     visudo: VISUDO_SHIM,
+    "opencode-polkit-env": POLKIT_ENV_HELPER,
 };
 /**
  * Writes the shim scripts into a fresh private directory and returns it.
  * The caller prepends this directory to PATH; the shell then resolves
  * `sudo`/`doas`/`su` to these files instead of the system ones. The directory
- * is 0700 so no other local user can rewrite the scripts.
+ * is 0700 so no other local user can rewrite the scripts, and it holds
+ * `opencode-polkit-env`, the helper `sudo -E` uses to re-export an environment
+ * pkexec stripped.
  */
 export function installPolkitShims() {
     const directory = mkdtempSync(join(shimBaseDirectory(), "opencode-polkit-"));

package/dist/shims.js.map

@@ -1 +1 @@
-{"version":3,"file":"shims.js","sourceRoot":"","sources":["../src/shims.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AACnF,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAChC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAE5C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,CAAA;AAEjC;;;;;;;;GAQG;AACH,MAAM,SAAS,GAAG;;;;;;QAMV,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmFtB,CAAA;AAED,yDAAyD;AACzD,MAAM,SAAS,GAAG;;;;;;QAMV,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuDtB,CAAA;AAED;;;;;GAKG;AACH,MAAM,OAAO,GAAG;;;;;;QAMR,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6FtB,CAAA;AAED,8EAA8E;AAC9E,MAAM,aAAa,GAAG;;OAEf,eAAe;CACrB,CAAA;AAED,qFAAqF;AACrF,MAAM,WAAW,GAAG;;OAEb,eAAe;CACrB,CAAA;AAED,+EAA+E;AAC/E,MAAM,mBAAmB,GAA2B;IAClD,IAAI,EAAE,SAAS;IACf,IAAI,EAAE,SAAS;IACf,EAAE,EAAE,OAAO;IACX,QAAQ,EAAE,aAAa;IACvB,MAAM,EAAE,WAAW;CACpB,CAAA;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,SAAS,GAAG,WAAW,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,kBAAkB,CAAC,CAAC,CAAA;IAC5E,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,CAAC;QACjE,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAA;QAClC,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;QAC3B,mEAAmE;QACnE,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;IACxB,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;GAGG;AACH,SAAS,iBAAiB;IACxB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAA;IAC3C,OAAO,OAAO,IAAI,UAAU,CAAC,OAAO,CAAC,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,EAAE,CAAA;AACnF,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,MAAM,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;AACrD,CAAC"}
+{"version":3,"file":"shims.js","sourceRoot":"","sources":["../src/shims.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-polkit",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Redirect sudo, doas and su to pkexec in OpenCode via PATH shims, so the system polkit agent handles authentication",
   "type": "module",
   "main": "./dist/index.js",