Repository navigation
Releases
Releases · lenitain/opencode-polkit
v0.4.1
[0.4.1] - 2026-11-07
Added
test/shims.test.ts: behaviour tests for the generated shims. They stub
pkexec,pkcheckandpkactiononPATH, so they need neither polkit, a
desktop agent nor root;npm testruns them with Node's test runner.- README: account-lockout section. Where the
polkit-1PAM 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,-vand-lcheck
org.freedesktop.policykit.execitself, while pkexec may select another
action installed withorg.freedesktop.policykit.exec.path/argv1
annotations.
Changed
- The shell tool's description 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-widepam_faillocklockout while a dismissal
does not. - README:
sudoersand thesudoPAM stack are not consulted; polkit policy and
thepolkit-1PAM service decide, so sudo-only modules such as a fingerprint
reader or a second factor do not run in OpenCode. - README now describes agent caching and retry behaviour generically instead of
attributing it to one desktop agent. sudo -vreports an interactive failure as "polkit did not authorize" instead
of "polkit denies", since the check can fail after the password is rejected.- The shim's action comment now records that pkexec may select a custom action by
annotation, which the checks do not see. npm run checknow also type-checkstest/, and CI runs check, test and
build.
v0.4.0
[0.4.0] - 2026-11-05
Added
sudo -n,doas -n: a non-interactivepkcheckon
org.freedesktop.policykit.execdecides whether the command runs. polkit grants
it without asking, or the shim exits1withsudo: a password is requiredand
the reason that dropping-nlets the agent answer. Measured: a successful
pkexecleaves no temporary authorization behind (pkcheck --list-tempstays
empty), so the silent second run is the agent's own password cache and no
non-interactive query can predict it;-ntherefore reports policy, not a
guess.sudo -vperforms the authentication (pkcheck --allow-user-interaction) and
exits0,1,126when the dialog is dismissed, or127;sudo -nvuses
the non-interactive check.sudo -lprintspkaction --verbosefor the action and this session's
temporary authorizations.sudo -k/-Krevoke polkit's temporary authorizations and say that an agent's
own password cache cannot be cleared from here.sudo -H,-N,-Pare accepted as no-ops: pkexec already setsHOME, keeps
no timestamp and leaves groups alone.sudo -s COMMANDand--shellrun the command through a shell,sudo -b
starts it in the background and returns, andsudo -E/
--preserve-env[=LIST]re-export the environment inside the command.sudo --helpandsudo -Vare 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 turnsNAME=VALUEarguments into export
statements.-Epasses entries through argv (env -0intoxargs -0), so
spaces, quotes and newlines survive, and it drops every shim directory from
PATHso 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,-vand-lanswer, 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,uidaspkcheck(1)requires), the two checks and thepkexec
wrapper. -nfailures exit1like sudo, not64:64now 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,sudoeditandvisudostill refuse, now from the shared
prelude.
v0.3.1
[0.3.1] - 2026-11-04
Added
src/shims.ts:sustand-in.su -c COMMAND [USER](also-cCOMMAND,
--command COMMAND,--command=COMMAND) becomes
pkexec --keep-cwd --user USER sh -c COMMAND, because a non-loginsukeeps
the working directory and runs its command through a shell. Every other form
is refused with status64and 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),-fand
--session-command.- README scope statement: the plugin covers elevation → polkit only; ssh,
gpg/pinentry, keyrings, database clients,kinitand 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 … USERauthenticates an
administrator rather thanUSER, and runs the command withsh -c.
v0.3.0
[0.3.0] - 2026-11-01
0.3.0 replaces how the plugin decides anything. It used to parse the command
string to find sudo, then parse the output to guess whether authentication
failed; both are gone. The plugin now only prepends a directory of shims to
PATH, letting the shell's own name resolution pick them, and reads the
outcome from exit status alone. Everything that existed to support guessing —
the lexical scanner, the output matchers, the denial cache, the translations —
is deleted with it. The plugin no longer changes the command the agent wrote.
Added
src/shims.ts:sudo,doas,sudoeditandvisudoscripts written to a
private0700temporary directory at setup and removed when the plugin is
disposed.sudoanddoasforward topkexec;sudoeditandvisudo
refuse, because polkit has no equivalent flow.- Deterministic option contract in the shims:
-u USER,-uUSER,--user USER
and--user=USERbecomepkexec --user USER,--ends option parsing, and
every other option is refused with exit status64and a message naming the
alternative (-n→ polkit decides,-i/-s→pkexec bash,-E/-H/-P
→ pkexec sanitizes the environment,-b→ append&).pkexecwould
otherwise reject them withCannot run program, which says nothing about what
to do next. - A one-line explanation on exit status
126: it is the only pkexec failure
path that prints nothing of its own, so the shim says the dialog was
dismissed. Every127path already prints its reason. SHIM_USAGE_EXIT(64) documents that the refusal status is the shim's own and
cannot be confused with pkexec's126/127.
Changed
- Breaking: commands are no longer rewritten. The
shelltool's
execute.before/execute.afterhooks are replaced by a single
shell.create.beforehook that only setsevent.env.PATH, so the agent's
command reaches the shell exactly as written, andsudoinside quotes,
comments or heredocs needs no special case. - Breaking: authentication failures are reported from exit status
(126dismissed,127not authorized,64refused invocation), never from
output. The locale-dependent matchers forNot authorized,
Error executing command as another userand
Error creating textual authentication agentare gone. - Breaking: messages are English only. The
Messagestable, the ten
translations anddetectLocaleare removed; the consumer is the coding agent. - Breaking: a refused command is no longer remembered. Retrying after a
dismissed dialog prompts again instead of being rejected by the plugin. - PATH interception is idempotent: prepending happens once, so stacked hooks do
not growPATH.
Removed
scanPrivileged(the quote-, escape- and heredoc-aware lexical scanner) and
findBadOption.- The
deniedCommandsandoriginalCommandsmaps, along with the
execute.afterresult rewriting they supported. - The
translationstable for en, zh, ja, ko, de, fr, es, pt, ru, tr and uk. - The i18n section of the README, which now documents the exit-status contract
and the PATH shim's limits instead.