pi-polkit 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] - 2026-11-04
+
+### Added
+
+- `polkit-shims.ts`: `su` stand-in. `su -c COMMAND [USER]` (also `-cCOMMAND`,
+  `--command COMMAND`, `--command=COMMAND`) becomes
+  `pkexec --keep-cwd --user USER sh -c COMMAND`, because a non-login `su`
+  keeps the working directory and runs its command through a shell. Every other
+  form is refused with status `64` and one line naming the alternative: `su`,
+  `su -`, `su -l` (login shell → `pkexec bash`), `-m`/`-p`/`-w` (pkexec
+  sanitizes the environment), `-s` (name the shell in the command), `-g`/`-G`
+  (pkexec cannot switch groups), `--pty` (no terminal), `-f` and
+  `--session-command`.
+- README scope statement: the extension covers elevation → polkit only;
+  ssh, gpg/pinentry, keyrings, database clients, `kinit` and disk encryption
+  are explicitly out of scope and need an askpass helper or a PTY.
+
+### Changed
+
+- README authorisation note: a desktop agent may reuse the password it already
+  holds, so a second command can run without a dialog; that cache belongs to
+  the agent and must not be relied on. `su -c … USER` authenticates an
+  administrator rather than `USER`, and runs the command with `sh -c`.
+
+## [0.1.0] - 2026-11-01
+
+### Added
+
+- `polkit-shims.ts`: `sudo`, `doas`, `sudoedit` and `visudo` scripts written to
+  a private `0700` directory under `$XDG_RUNTIME_DIR` (falling back to `/tmp`)
+  on first use and removed at session shutdown. `sudo` and `doas` forward to
+  `pkexec`; `sudoedit` and `visudo` refuse, because polkit has no equivalent
+  flow.
+- Deterministic option contract in the shims: `-u USER`, `-uUSER`, `--user USER`
+  and `--user=USER` become `pkexec --user USER`, `--` ends option parsing, and
+  every other option is refused with exit status `64` and a message naming the
+  alternative (`-n` → polkit decides, `-i`/`-s` → `pkexec bash`, `-E`/`-H`/`-P`
+  → pkexec sanitizes the environment, `-b` → append `&`). `pkexec` would
+  otherwise reject them with `Cannot run program`, which says nothing about what
+  to do next.
+- `polkit-redirect.ts`: the Pi extension factory. The `bash` tool is
+  replaced by the built-in's own definition with a
+  `spawnHook` that prepends the shim directory to `PATH`, and `!` user commands
+  run through `createLocalBashOperations` with the same prepend as their first
+  command line. Command text is never rewritten.
+- Authentication outcomes are reported from exit status alone (`126` dismissed,
+  `127` not authorized, `64` refused invocation); the shims print one line
+  explaining status `126`, the only pkexec failure path that is silent.
+- `SHIM_USAGE_EXIT` (64) documents that the refusal status is the shim's own
+  and cannot be confused with pkexec's `126`/`127`.
+- Engineering scaffolding: `npm run check` type-checks against the pinned
+  `@earendil-works/pi-coding-agent` 1.4.0, and GitHub Actions CI runs it on
+  every push and pull request.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-polkit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# pi-polkit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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):
+
+```sh
+pi install npm:pi-polkit
+```
+
+Or copy or symlink this directory into Pi's extension location:
+
+```sh
+cp -r pi-polkit ~/.pi/agent/extensions/pi-polkit
+```
+
+For a quick test without installing, pass the directory to Pi:
+
+```sh
+pi -e ./pi-polkit
+```
+
+## Behavior
+
+| Command                | Result                                      |
+|------------------------|---------------------------------------------|
+| `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        |
+| `sudoedit`, `visudo`   | refused, with the alternative               |
+| `su -c 'id'`           | dialog, then runs as root                   |
+| `su -c 'id' bob`       | as above, as `bob` (administrator password) |
+| `su`, `su -`, `su -l`  | refused: no interactive shell, no terminal  |
+| `su -m`, `-s`, `-g`, `-w`, `--pty` | refused, with the alternative   |
+| `pkexec …`             | passed through                              |
+
+Refused invocations exit with status 64 and one line naming the alternative.
+
+## How it works
+
+`sudo`, `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.
+
+Two wiring paths put the stand-ins on `PATH`, one per execution form:
+
+- The `bash` tool is replaced by the built-in's own definition with a
+  `spawnHook` that prepends the shim directory to the spawned environment.
+- `!` user commands run through Pi's local bash backend with no prepared
+  environment, so their wrapper prepends `export PATH=…` as the first command
+  line instead.
+
+The shim directory is created lazily in `$XDG_RUNTIME_DIR` (falling back to
+`/tmp`) as `0700` and removed at session shutdown.
+
+## Authorisation
+
+`polkitd` decides whether a password is required. These commands always require
+one; other actions may not, according to policy. The extension takes no part in
+that decision.
+
+`org.freedesktop.policykit.exec` asks for administrator authentication on every
+call, but the desktop agent may keep the password it just received and answer
+the next challenge itself (KDE's agent does). A second command in the same
+session then runs without a dialog. That cache belongs to the agent: another
+agent, a restarted agent or a dismissed dialog means the next command prompts
+again, so do not rely on it.
+
+## Limitations
+
+- Absolute paths (`/usr/bin/sudo`) and relative ones (`./sudo`) bypass `PATH`.
+- Commands that reset `PATH` (`env -i`, `PATH=/usr/bin …`) bypass it as well.
+- Programs that invoke `sudo` with a scrubbed environment bypass it.
+- `su -c … USER` authenticates an administrator (polkit), not `USER`, so an
+  account that real `su` would allow can be refused here.
+- `su -c` runs the command with `sh -c`, not with the target user's login shell.
+- PowerShell is not handled; the extension targets Linux only.
+
+These bypass the redirect, not polkit, which still decides whether the command
+runs.
+
+## Requirements
+
+`polkit` and a registered authentication agent. Desktop environments start one;
+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         |
+
+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.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./polkit-redirect"

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "pi-polkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Redirect sudo, doas and su to pkexec in Pi via PATH shims, so the desktop polkit agent handles authentication",
+  "type": "module",
+  "pi": {
+    "extensions": ["./index.ts"]
+  },
+  "files": [
+    "index.ts",
+    "polkit-redirect.ts",
+    "polkit-shims.ts",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "check": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run check"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "keywords": ["pi-package", "pi-extension", "sudo", "doas", "su", "pkexec", "polkit", "security"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lenitain/pi-polkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lenitain/pi-polkit/issues"
+  }
+}

package/polkit-redirect.ts

@@ -0,0 +1,45 @@
+import type { BashOperations, ExtensionAPI } from "@earendil-works/pi-coding-agent"
+import { createBashToolDefinition, createLocalBashOperations } from "@earendil-works/pi-coding-agent"
+import { polkitShimsPathExportLine, removePolkitShims, withPolkitShimsOnPath } from "./polkit-shims"
+
+/**
+ * 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/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
+ * (126 dismissed, 127 not authorized) back to the caller unchanged.
+ */
+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) }),
+    }),
+  )
+
+  pi.on("user_bash", () => ({ operations: polkitShimsUserBashOperations() }))
+
+  // The shims are session-scoped; the next session recreates them lazily.
+  pi.on("session_shutdown", () => removePolkitShims())
+}
+
+/**
+ * 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.
+ */
+function polkitShimsUserBashOperations(): BashOperations {
+  const local = createLocalBashOperations()
+  return {
+    exec: (command, cwd, options) => local.exec(`${polkitShimsPathExportLine()}\n${command}`, cwd, options),
+  }
+}

package/polkit-shims.ts

@@ -0,0 +1,371 @@
+import { chmodSync, existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { isAbsolute, join } from "node:path"
+
+/**
+ * Exit status every shim uses for an invocation pkexec cannot express
+ * (EX_USAGE). Distinct from pkexec's own 126 (dismissed) and 127 (not
+ * authorized or failed) so callers can tell the two apart without reading
+ * any output.
+ */
+export const SHIM_USAGE_EXIT = 64
+
+/**
+ * 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.
+ */
+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() {
+	printf 'pi-polkit: %s\\n' "$1" >&2
+	exit ${SHIM_USAGE_EXIT}
+}
+
+command -v pkexec >/dev/null 2>&1 || fail 'pkexec is not installed; install polkit'
+
+user=
+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.'
+		;;
+	-v | --validate | -k | --reset-timestamp | -K | --remove-timestamp)
+		fail 'sudo credential caching does not exist under polkit; drop -v/-k.'
+		;;
+	-l | --list)
+		fail 'sudo -l is not available under polkit; inspect policy with pkaction --verbose.'
+		;;
+	-e | --edit)
+		fail 'sudoedit is not supported; write a temp file and run pkexec install or pkexec cp on it.'
+		;;
+	-i | --login | -s | --shell)
+		fail 'sudo -i/-s opens a login shell; run pkexec bash instead.'
+		;;
+	-S | --stdin)
+		fail 'sudo -S reads the password from stdin; pkexec authenticates through the polkit agent. Drop -S.'
+		;;
+	-A | --askpass)
+		fail 'SUDO_ASKPASS does not apply to pkexec; drop -A.'
+		;;
+	-b | --background)
+		fail 'sudo -b backgrounds the command; append & instead.'
+		;;
+	-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)"
+		;;
+	*)
+		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 "$@"
+	status=$?
+	if [ $status -eq 126 ]; then
+		printf 'pi-polkit: %s\n' 'the polkit authentication dialog was dismissed' >&2
+	fi
+	exit $status
+}
+
+if [ -n "$user" ]; then
+	run_pkexec --user "$user" "$@"
+fi
+run_pkexec "$@"
+`
+
+/** The doas shim: same contract, doas option grammar. */
+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'
+
+user=
+while [ $# -gt 0 ]; do
+	case $1 in
+	--)
+		shift
+		break
+		;;
+	-u)
+		[ $# -ge 2 ] || fail 'doas -u needs a username: -u USER PROGRAM'
+		user=$2
+		shift 2
+		;;
+	-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.'
+		;;
+	-s)
+		fail 'doas -s opens a shell; run pkexec bash instead.'
+		;;
+	-C | -a | -L)
+		fail "option has no pkexec equivalent: $1"
+		;;
+	-?*)
+		fail "unknown doas option: $1"
+		;;
+	*)
+		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 "$@"
+	status=$?
+	if [ $status -eq 126 ]; then
+		printf 'pi-polkit: %s\n' 'the polkit authentication dialog was dismissed' >&2
+	fi
+	exit $status
+}
+
+if [ -n "$user" ]; then
+	run_pkexec --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.
+
+fail() {
+	printf 'pi-polkit: %s\\n' "$1" >&2
+	exit ${SHIM_USAGE_EXIT}
+}
+
+command -v pkexec >/dev/null 2>&1 || fail 'pkexec is not installed; install polkit'
+
+user=
+cmd=
+has_cmd=
+while [ $# -gt 0 ]; do
+	case $1 in
+	--)
+		shift
+		break
+		;;
+	-c)
+		[ $# -ge 2 ] || fail 'su -c needs a command: su -c COMMAND [USER]'
+		cmd=$2
+		has_cmd=1
+		shift 2
+		;;
+	-c?*)
+		cmd=\${1#-c}
+		has_cmd=1
+		shift
+		;;
+	--command)
+		[ $# -ge 2 ] || fail 'su --command needs a command: su --command COMMAND [USER]'
+		cmd=$2
+		has_cmd=1
+		shift 2
+		;;
+	--command=*)
+		cmd=\${1#--command=}
+		has_cmd=1
+		shift
+		;;
+	- | -l | --login)
+		fail 'su starts a login shell; run pkexec bash instead.'
+		;;
+	-s | --shell | -s?* | --shell=*)
+		fail 'su -s picks the shell; name the shell in the command: pkexec sh -c ...'
+		;;
+	-m | -p | --preserve-environment)
+		fail 'pkexec deliberately sanitizes the environment; drop -m/-p.'
+		;;
+	-g | -G | --group | --supp-group | -g?* | -G?* | --group=* | --supp-group=*)
+		fail 'su -g/-G switches groups; pkexec can only switch users.'
+		;;
+	-w | --whitelist-environment | -w?* | --whitelist-environment=*)
+		fail 'su -w whitelists environment variables; pkexec sanitizes the environment.'
+		;;
+	-P | --pty)
+		fail 'su --pty asks for a terminal; the bash tool has none.'
+		;;
+	-f | --fast)
+		fail 'su -f is a shell flag; pass it to the shell in the command instead.'
+		;;
+	--session-command | --session-command=*)
+		fail 'su --session-command keeps the session; pkexec always starts a new process.'
+		;;
+	-h | --help | -V | --version)
+		fail "option has no pkexec equivalent: $1"
+		;;
+	-?*)
+		fail "unknown su option: $1"
+		;;
+	*)
+		[ -z "$user" ] || fail 'su passes arguments after the user name to the shell; use su -c COMMAND USER.'
+		user=$1
+		shift
+		;;
+	esac
+done
+
+# Operands after -- are the same user-then-nothing sequence.
+while [ $# -gt 0 ]; do
+	[ -z "$user" ] || fail 'su passes arguments after the user name to the shell; use su -c COMMAND USER.'
+	user=$1
+	shift
+done
+
+[ -n "$user" ] || user=root
+[ -n "$has_cmd" ] || fail 'su without -c opens an interactive shell; run pkexec bash instead.'
+
+# su keeps the working directory unless it is a login shell, and --keep-cwd is
+# how pkexec does the same. pkexec is silent when the dialog is dismissed
+# (status 126), so say what the status means.
+pkexec --keep-cwd --user "$user" sh -c "$cmd"
+status=$?
+if [ $status -eq 126 ]; then
+	printf 'pi-polkit: %s\\n' 'the polkit authentication dialog was dismissed' >&2
+fi
+exit $status
+`
+
+/** sudoedit edits through sudo's own temporary-file flow; polkit has none. */
+const SUDOEDIT_SHIM = `#!/bin/sh
+printf 'pi-polkit: sudoedit is not supported; write a temp file and run pkexec install or pkexec cp on it.\\n' >&2
+exit ${SHIM_USAGE_EXIT}
+`
+
+/** 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}
+`
+
+/** 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,
+}
+
+/** Shim directory of the running extension; created on first use, cleared by removePolkitShims. */
+let shimDirectory: string | undefined
+
+/**
+ * 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 {
+  shimDirectory ??= installPolkitShims()
+  return shimDirectory
+}
+
+/**
+ * Deletes the shim directory created by ensurePolkitShims. Idempotent, and the
+ * next use recreates the directory, so it can run at every session shutdown.
+ */
+export function removePolkitShims(): void {
+  if (!shimDirectory) return
+  rmSync(shimDirectory, { recursive: true, force: true })
+  shimDirectory = undefined
+}
+
+/**
+ * Returns the environment with the shim directory first on PATH, so the shell
+ * 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.
+ */
+export function withPolkitShimsOnPath(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const prefix = `${ensurePolkitShims()}:`
+  const path = env.PATH ?? ""
+  return path.startsWith(prefix) ? env : { ...env, PATH: prefix + path }
+}
+
+/**
+ * A shell line that puts the shim directory first on PATH, for execution paths
+ * that receive no prepared environment (the `!` user commands run through a
+ * shell, so the prepend happens as their first command line).
+ */
+export function polkitShimsPathExportLine(): string {
+  return `export PATH="${ensurePolkitShims()}:$PATH"`
+}
+
+/**
+ * Writes the shim scripts into a fresh private directory and returns it. The
+ * directory is 0700 so no other local user can rewrite the scripts.
+ */
+function installPolkitShims(): string {
+  const directory = mkdtempSync(join(shimBaseDirectory(), "pi-polkit-"))
+  for (const [name, script] of Object.entries(POLKIT_SHIM_SCRIPTS)) {
+    const file = join(directory, name)
+    writeFileSync(file, script)
+    // writeFileSync's mode is filtered by umask, so set it explicitly.
+    chmodSync(file, 0o755)
+  }
+  return directory
+}
+
+/**
+ * Where shim directories live. Prefers the login session's runtime directory,
+ * which the system clears on logout, over /tmp which keeps leftovers.
+ */
+function shimBaseDirectory(): string {
+  const runtime = process.env.XDG_RUNTIME_DIR
+  return runtime && isAbsolute(runtime) && existsSync(runtime) ? runtime : tmpdir()
+}