# `polkit`

Strand's own polkit authentication agent: the password dialog when a
program asks for something that needs one. While a config reads
`polkit`, Strand registers as this session's agent with polkit
(unless another agent already is, which it leaves be), and each
request polkit sends becomes `request` until it is answered,
cancelled, or withdrawn by the program. The password goes to polkit's
own helper (`polkit-agent-helper-1`), never checked by Strand, and is
wiped once sent. A panel shows it:
`panel Polkit { open: polkit.request != null; keyboard: exclusive … }`.

| Field | Type | |
| --- | --- | --- |
| `request` | `PolkitRequest?` | The request being answered, or null when none waits. |
| `waiting` | `int` | How many more requests wait behind `request`, each shown in turn. |
| `busy` | `bool` | An answer is being checked. |
| `failed` | `bool` | The last answer was refused: `request` stays, and its prompt asks again. |
| `available` | `bool` | Strand is this session's polkit agent. False while another agent is (a desktop's own, `polkit-gnome`), and when it cannot be one: polkit's helper (`polkit-agent-helper-1`, setuid root, or polkit's own socket for it) is not installed, polkit is not running, or Strand runs in no login session; `error` says which. |
| `error` | `text` | Why Strand is not the agent ("another polkit authentication agent already serves this session…"), or why the shown request's check could not run or ended early; "" otherwise. |

| Method | |
| --- | --- |
| `action respond(answer: text)` | Answers `request.prompt` with `answer` (the password): `input { type: password; text: <-> pw; on activate { polkit.respond(pw); pw = "" } }`. Ignored while one is being checked, and when the request shown has not asked yet (it went, or another user was chosen, since the answer was typed: an answer is never given to a request it was not typed for). After a refusal an answer typed before the check asks again waits for that question, and only a secret one (not `echo`) takes it. Pass a password to nothing else: the config is trusted code, and a declared action's arguments can be read by every user in the process list. |
| `action cancel()` | Dismisses `request`: the program is told it was refused, and the next request, if any, shows. |
| `action choose(user: text)` | Asks for `user`'s password instead (one of `request.users`). |