feature: web.shell lets /shell of the web service open a login shell of web.shell_user over a WebSocket for the Router Manager's Shell page, after the user signs in again.

README.md

@@ -128,6 +128,9 @@ must have the type shown below; an unknown section or setting is an error.
 | `web` | `database` | string | | A PostgreSQL connection string for the refresh tokens; without it, the `vpn-router` database on this host that the web service creates |
 | `web` | `trusted_proxies` | list | the address the call came in on | Addresses whose `X-Forwarded-For` header names the client for the `/auth` rate limit and the Client IP of the status |
 | `web` | `status_content` | string | `basic` | What `/` and `/status` show: `basic`, `standard` or `full` (see Status web service) |
+| `web` | `shell` | boolean | `false` | `/shell` opens a login shell of `shell_user` for a member of `admins` (see The shell) |
+| `web` | `shell_user` | string | | The system user the shell runs as, not `root`; required by `shell` |
+| `web` | `shell_idle_minutes` | integer | `15` | Minutes without a keystroke after which a shell is closed, 1 to 1440 |
 | `https` | `enabled` | boolean | `true` | Caddy serves the status web service and the Router Manager over HTTPS for `wan.local_fqdn` |
 | `https` | `email` | string | | The e-mail address of the Let's Encrypt account |
 | `https` | `web_port` | integer | `7444` | HTTPS port of the status web service |
@@ -865,7 +868,7 @@ curl http://10.0.0.4:7081/status
 
 ### Tokens and signing in
 
-`/config`, `/users`, `/service-accounts`, `/groups`, `/site-to-site` and `/account` need a JWT in an `Authorization: Bearer` header, signed with
+`/config`, `/users`, `/service-accounts`, `/groups`, `/site-to-site`, `/shell` and `/account` need a JWT in an `Authorization: Bearer` header, signed with
 HS256 by the key the web service makes on its first run, `/etc/vpn-router/web.key` (root only).
 The key never leaves the router; while it does not exist these paths and `/auth` are not served
 (404). A missing, expired or wrongly signed token, or one of another algorithm, gets 401 with
@@ -923,6 +926,33 @@ curl -H "Authorization: Bearer $TOKEN" http://10.0.0.4:7081/config
 does with `web.status_content` `full`, whatever that setting says, so the Router Manager shows
 every service and tunnel while the public status page shows less.
 
+### The shell
+
+While `web.shell` is `true`, `/shell` gives a member of `admins` a login shell on the router, as
+the system user `web.shell_user`, for the Router Manager's Shell page. It is off by default and
+switched on and off on the router only:
+
+```sh
+vpn-config-edit set web.shell_user azureuser
+vpn-config-edit set web.shell true
+```
+
+| Request | Body | Answer |
+| --- | --- | --- |
+| `POST /shell` | `{"password", "code"}`; `code` only for a user enrolled for TOTP | `{"ticket", "expires_in": 30}` |
+| `GET /shell?ticket=<ticket>` | a WebSocket handshake | the terminal |
+
+`POST /shell` needs an access token of `/auth`, not one of `vpn-router-token`, and signs its user
+in again: a wrong password or code gets 403 and counts as a failed login. The ticket opens one
+shell for the same user within 30 seconds. Over the WebSocket, binary messages of the client
+are keystrokes, a text message `{"cols", "rows"}` sets the window size, and binary messages of
+the router are the terminal's output. The shell is a PAM login session of `web.shell_user`, run
+by `systemd-run` in a transient unit `vpn-router-shell-<id>`; sudo works as the user's sudoers
+entry allows. It is closed after `web.shell_idle_minutes` without a keystroke, when the shell
+exits, or when the connection closes; the router then sends a close frame with the reason. The
+journal of `vpn-router-web` records who opened each shell, from which address, in which unit,
+when it ended and why.
+
 ### The /config page
 
 `/config` shows what `/` and `/status` leave out, for a client such as manage-ui: