pi-polkit 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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

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
 
@@ -47,7 +47,7 @@ pi -e ./pi-polkit
 | `sudo -u bob …`        | as above, as `bob`                          |
 | `cat x \| sudo tee y`  | dialog for `tee`                            |
 | `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 -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 |
@@ -93,20 +93,66 @@ pkexec stripped.
 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.
-
-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.
+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
 
@@ -116,6 +162,10 @@ dialog would appear, and why `sudo -k` can only clear polkit's own record.
 - `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.
@@ -135,18 +185,19 @@ without one, `pkexec` fails instead of prompting.
 
 | Status | Meaning                                                |
 |--------|--------------------------------------------------------|
-| 1      | `-n` or `-v` could not be satisfied: polkit requires authentication, or refuses |
+| 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, or the program could not run           |
+| 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.2.0",
+  "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
@@ -25,7 +25,7 @@ export default function polkitRedirect(pi: ExtensionAPI): void {
   // The model plans privilege with what it knows about sudo. Say once, in the
   // system prompt, how this shell differs, so it does not learn it by failing.
   bash.promptGuidelines?.push(
-    "`sudo`, `doas` and `su -c` are routed to pkexec, so a desktop polkit dialog authorises them instead of a terminal password prompt. `sudo -n` runs the command only if polkit would authorise it without asking, `sudo -v` performs the authentication, and `sudo -l` prints the polkit policy that decides.",
+    "`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)
 

package/polkit-shims.ts

@@ -309,7 +309,7 @@ if [ "$mode" = validate ]; then
 		exit 0
 		;;
 	1)
-		printf 'pi-polkit: sudo: polkit denies %s to this process\\n' "$ACTION" >&2
+		printf 'pi-polkit: sudo: polkit did not authorize %s (the policy denies it, or authentication failed)\\n' "$ACTION" >&2
 		exit 1
 		;;
 	2)