feat(terminal): interactive terminal in cluster-admin over SSH, login inside the pane

[stephdl]

Adds an interactive terminal to cluster-admin, towards any cluster node. sshd
on the target node creates the pseudo-terminal; api-server opens the SSH
connection over the WireGuard VPN and relays the byte stream to the browser.

Disabled on every node by default. docs/core/terminal.md carries the full
rationale.

The login prompt runs inside the terminal

There is no credentials form. The pane opens as soon as the websocket does,
api-server draws a login: prompt, and the password questions come from sshd
over keyboard-interactive.

SSH carries the user name in the authentication request, so there is no remote
login prompt to relay: api-server draws that one itself, which is why it does
its own line editing.

This does not narrow who can read the password. It still crosses api-server in
clear on its way to the node, exactly as a credentials frame would. What it
removes is the password field, and the browser vault entry that field invited.

What it is, and what it is not

A jump host. open-terminal does not grant root. It grants the right to
reach port 22 of a node through the cluster VPN, which is usually not routable
from an administrator's workstation. sshd still authenticates a system
account with a password supplied by the user.

The design assumes two administrator populations: "NS8 cluster admin" and
"operating system admin" may be different people. open-terminal can be
granted on a single node to an operator holding no other privilege there, and
an NS8 owner cannot get a shell without system credentials. This is why the
authentication factor always comes from the user, and why nothing here writes
to authorized_keys.

A key enrolment action was considered and dropped: owner holds * on every
node, so it would hold any enrolment action by construction, enrol itself and
obtain root with no system factor.

Enabling a node changes its sshd configuration

enable-node-terminal sets the flag and the node writes
/etc/ssh/sshd_config.d/90-ns8-terminal.conf, which allows password
authentication from the cluster VPN only, on an opted-in node only.
prohibit-password has been OpenSSH's compiled-in default since 7.0, so
without that drop-in root cannot log in with a password on either supported
family.

sshd -t runs before any reload and the drop-in is reverted if validation
fails, so a syntax error cannot take sshd down. The action fails loudly when
sshd_config has no Include /etc/ssh/sshd_config.d/*.conf, because the file
would be inert and reporting success would be a lie. set-terminal-sshd takes
no parameter: it reads the flag and converges the drop-in to it, so a caller
can only realign the node with the cluster policy, never open password
authentication on its own.

Notable decisions

• The REST route only authorizes and mints a one-shot ticket, bound to the
  client address and to a single node reservation.
• The browser sends only a node id. Address and port come from Redis; taking a
  host from the client would make api-server an arbitrary SSH proxy.
• Host keys are published by the node into node/<id>/ssh and accepted from
  there. This is not pinning: a regenerated key is accepted as soon as it
  is republished. The property is that the key arrives over the cluster's
  authenticated channel.
• A dedicated melody instance, because the shared /ws keeps melody's 512 byte
  read limit that a paste would exceed, and raising it there would raise it for
  an endpoint reachable without authentication.
• The disabled flag is re-read on every keepalive tick, and by a watchdog
  during login, so disabling a node closes live sessions and also interrupts
  one parked at the password prompt.
• Only enabled is written to node/<id>/terminal. Who flipped it belongs in
  audit.db, which modules cannot read, whereas node/* is readable by every
  installed module through its %R~node/* grant.

Security

api-server sees everything typed, the system password included. Inherent to
any browser terminal, and end-to-end encryption would not help, since
api-server serves the JavaScript that would perform it.

This is not an escalation the feature opens. api-server's Redis ACL is ~* on
keys and &* on channels with lpush, and NS8 dispatches work by pushing onto
task/<agent>/…, so that access already queues arbitrary actions on any node
agent, which runs as root. Whoever controls api-server holds the cluster
without needing anyone's password.

What the terminal adds is persistence rather than access. Cluster secrets are
rotated by rebuilding: JWT secret, Redis ACL passwords, WireGuard keys. A node
root password is not. It stays valid after a rebuild and carries outside NS8
wherever it is reused. The cluster-admin password already travels the same path,
reaching Redis as an AUTH command, but it is a cluster secret and rotates with
the cluster.

/ws/terminal carries no JWT middleware. Access rests on the one-shot
ticket: minted only by an authenticated POST holding open-terminal, bound to
the client address, valid 30 seconds. A caller without one gets a socket that
closes with nothing. Cross-origin hijacking does not apply either, as
authentication is not cookie-based and a third-party page cannot read the
ticket. What is missing is a cap: nothing limits concurrent connections to this
endpoint, and each unauthenticated one holds a session and a 30 second timer.
The pre-existing /ws has the same exposure.

open-terminal is a password oracle. It allows testing system passwords
against sshd from an address in firewalld's trusted zone, bypassing network
restrictions set for external access. Resistance rests entirely on the
api-server throttle, since pam_faillock has even_deny_root disabled by
default and is absent from Debian's default stack. Failed handshakes are
audited with the cluster-admin identity, which lastb cannot show.

CrowdSec can ban the leader and cut a node out of the cluster. All terminal
traffic reaches a node from the leader's VPN address, so sshd attributes
failed logins to it and never to the real client. Reproduced on the test
cluster: four failed attempts produced eight crowdsecurity/ssh-bf events and a
ban of 10.5.4.1 on the node. The firewall bouncer drops the source address on
all ports, not just SSH, so Redis replication and the node agent went down
with the terminal — the replication link had to re-establish afterwards. The ban
was one minute here; with CrowdSec's default duration the node would leave the
cluster for four hours, and it cannot be repaired from the UI, because the UI
drives the node through the very connection that is blocked.

The trigger is an administrator mistyping a root password.

CrowdSec should be patched to never ban the cluster VPN network. That is the
only mitigation covering every source of failures coming from the leader, not
just this feature. Spacing the attempts on the api-server side reduces the rate
but does not close the hole.

Verified

Built here: go build, go vet, gofmt clean, yarn lint, yarn build.

On a two-node test cluster, Rocky 9 leader and Debian 13 node: sessions opened
against both nodes, Include /etc/ssh/sshd_config.d/*.conf present and the
drop-in effective on Debian 13, sshd -T -C returning the expected fields after
activation, host keys published and used by the handshake, audit rows and the
ns8-terminal correlation line landing on the node.

@xterm/xterm 5.5 does not build: webpack 4, pinned by vue-cli 4, cannot parse
its bundle. The 5.3 series is used instead.

Not verified

• Debian 12.
• The audit join on the local TCP port, which depends on the default LogLevel.
• No automated integration test covers a session.

Capture.video.du.2026-08-03.13-18-25.mp4