pi-polkit 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# 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.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,99 @@
-# 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` and `doas` 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.
+
+## 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               |
+| `pkexec …`             | passed through                              |
+
+Refused invocations exit with status 64 and one line naming the alternative.
+
+## How it works
+
+`sudo` and `doas` stand-ins are placed first on `PATH`, so the shell resolves
+those instead of the system binaries, and they forward the command to
+`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.
+
+## 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.
+- 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.0",
+  "description": "Redirect sudo/doas 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", "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 and doas to pkexec inside Pi, so authorisation goes
+ * through the desktop's polkit agent (KDE, GNOME, …) instead of a terminal the
+ * shell tools do not have. Applies to the `bash` tool and to `!` user
+ * commands; `sudo` in other terminals is unchanged.
+ *
+ * The redirect is a PATH prepend, not a command rewrite: the shims in
+ * polkit-shims.ts stand in for the sudo/doas binaries, and the shell's own
+ * 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 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,263 @@
+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 "$@"
+`
+
+/** 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,
+  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 sudo/doas 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 and doas 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()
+}