swarmctl: log in with the operator's own SSO account and reach the controller through the swarm domain

`swarmctl --swarm https://<swarm> login` runs the OAuth 2.0
authorization-code flow with PKCE against the swarm's authelia as a new
public `swarmctl` client: a pushed authorization request, the browser login
and explicit consent, and the code delivered by form_post to a loopback
port. The access and refresh tokens are cached at mode 0600 under
$XDG_STATE_HOME/swarmctl/ and refreshed under a file lock, since authelia
rotates the refresh token and revokes the login when a used one is
presented again. With --swarm (or SWARMCTL_SWARM), the agent, schedule and
forge verbs send their requests to https://<swarm>/api/ with the bearer
token instead of over the controller's unix socket, which stays the default.

authelia registers the client on every authelia host with a swarm domain:
`kind = "native"`, public, no minted secret, scopes offline_access and
authelia.bearer.authz, audience https://<swarm>/api/ (matched as a URL
prefix), redirect http://127.0.0.1/callback (any loopback port). Every
field is one authelia 4.39.20's validator requires for a public client
holding the bearer scope.

The swarm apex's /api/ answers a refused caller that sent an
Authorization header with the 401 itself instead of the login redirect,
so the CLI can tell "log in again" apart from an answer; a browser still
gets the redirect. The bearer token is not forwarded to the controller.

Refs #4409 (mara: c94764, c94782).

docs/swarm/sso.md

@@ -281,6 +281,17 @@ All three matter. A change that silently deleted the browser page would
 pass a deny-only check, and one that quietly stopped denying would pass a
 page-only check. The person who introduced the split verified it this way.
 
+## Operator CLI login
+
+`swarmctl login` logs an operator in as their own account, from any
+machine, through the public `swarmctl` client authelia always registers: no
+secret, authorization code with PKCE, a loopback redirect, and a refresh
+token. Its access token carries `authelia.bearer.authz` with the audience
+`https://<swarm>/api/`, so the gateway admits it at the controller's API and
+nowhere else, under the same access rule as a browser session there.
+Revocation is per account: once authelia stops accepting the account, the
+gateway refuses its token too. See [`swarmctl/README.md`](../../swarmctl/README.md#remote-use-swarmctl-login).
+
 ## What this doesn't do
 
 - **It doesn't disable local login — except on Grafana.** Forgejo and

docs/tools/swarmctl-cli.md

@@ -27,6 +27,7 @@ This document contains the help content for the `swarmctl` command-line program.
 * [`swarmctl user list`↴](#swarmctl-user-list)
 * [`swarmctl forge`↴](#swarmctl-forge)
 * [`swarmctl forge make-admin`↴](#swarmctl-forge-make-admin)
+* [`swarmctl login`↴](#swarmctl-login)
 * [`swarmctl completions`↴](#swarmctl-completions)
 
 ## `swarmctl`
@@ -41,6 +42,7 @@ swarm-level operator CLI
 * `schedule` — Manage scheduled prompts
 * `user` — Manage subjects in the swarm's SSO provider
 * `forge` — Manage human accounts on the swarm's forge
+* `login` — Log in to the swarm named by `--swarm` as your own SSO account
 * `completions` — Generate a shell completion script for `swarmctl` and print it to stdout
 
 ###### **Options:**
@@ -49,6 +51,8 @@ swarm-level operator CLI
 * `--users-file <PATH>` — Host-side path of authelia's users database — that is, the path inside the container, prefixed with the container's root.
 
    This is the only user store: it's read before every change and written in place, and `swarm-authelia-bridge` writes the same file.
+* `--swarm <URL>` — The swarm's domain, as `https://<domain>`. Given, the `agent`, `schedule` and `forge` verbs go through its gateway as the account `swarmctl login` logged in, instead of over the controller's socket. Falls back to `SWARMCTL_SWARM`
+* `--ca-file <PATH>` — A PEM CA certificate to trust beside the system roots, for a swarm whose gateway serves a certificate from the swarm's own CA. Falls back to `SWARMCTL_CA_FILE`
 
 
 
@@ -75,7 +79,7 @@ Asks the swarm-controller to insert its agent-creation job graph — SSO identit
 
 **This returns as soon as it queues the work.** It doesn't wait, and a finished graph would not mean the agent is up either: the last node publishes a deploy, after which the hive converges on its own clock. Watch the swarm UI's job view, or the hive itself, for the rest.
 
-No approval gate guards this: running this binary already means being root on the controller's host.
+No approval gate guards this: the caller is root on the controller's host, or logged in through the swarm domain's SSO gate.
 
 **Usage:** `swarmctl agent create [OPTIONS] --hive <HIVE> <NAME>`
 
@@ -465,6 +469,16 @@ The forge creates a human's account on their first SSO login, and this fails unt
 
 
 
+## `swarmctl login`
+
+Log in to the swarm named by `--swarm` as your own SSO account.
+
+Opens the swarm's SSO login in your browser (and prints the URL) and receives the answer on a loopback port, so run it where that browser runs. swarmctl keeps the login, mode 0600, under `$XDG_STATE_HOME/swarmctl/` and refreshes it as it's used. To log out, delete that file.
+
+**Usage:** `swarmctl login`
+
+
+
 ## `swarmctl completions`
 
 Generate a shell completion script for `swarmctl` and print it to stdout.