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.

ADR.md

@@ -895,3 +895,29 @@ Consequences: `slapcat` writes the users and the PKI into every backup in one co
 restore brings both back together. The PKI depends on slapd, as the users already do, and not on
 PostgreSQL. The directory holds the CA keys, so it is as sensitive as the CA itself. The schema
 grows by the package's PKI attributes and classes, which setup adds to slapd's configuration.
+
+## ADR-33: The web service opens a shell for the Router Manager over a WebSocket
+
+Context: The Router Manager's Shell page gives an administrator a terminal on the router in the
+browser, with xterm.js, the terminal of VS Code. A terminal needs a full-duplex channel, which
+xterm.js expects as a WebSocket. The web service runs in a sandbox (`NoNewPrivileges`,
+`ProtectSystem=strict`, `ProtectHome`) that a shell must not inherit, and as root, which a shell
+in a browser should not be. A stolen session cookie or access token alone must not give a shell.
+
+Decision: `/shell` of the web service is off until `web.shell` is set on the router; the Router
+Manager cannot set it. The shell runs as `web.shell_user`, a system user other than root, which
+reaches root through its sudoers entry. `POST /shell` signs the user in again with the password
+and TOTP code and gives a one-time ticket valid 30 seconds; a WebSocket on `GET /shell` with that
+ticket gets the shell. The WebSocket of RFC 6455 is implemented on the standard library inside the
+web service's `http.server`, server side only, without extensions. `systemd-run --pty` starts the
+shell in a transient unit with a PAM login session, outside the sandbox, and `setsid --ctty`
+makes the terminal its controlling terminal so window sizes reach the shell. A shell idle for
+`web.shell_idle_minutes` is closed, and the journal records every opening and end. The Router
+Manager checks the session and the WebSocket's origin, and relays the bytes to the router after
+both handshakes.
+
+Consequences: Who can sign in as a member of `admins` and knows the password and the current code
+can get a shell when the router allows one; a session alone cannot. The ticket travels in the URL
+and appears in request logs, used up. The shell's sessions show up as `vpn-router-shell-<id>`
+units and logind sessions of `web.shell_user`. The shell's traffic is as protected as the Router
+Manager's: HTTPS to Caddy, plain HTTP on the internal network to the web service.