# Ein Terminal auf dem Host, aus der Konsole heraus

**Stand:** Entwurf, 2. August 2026
**Entschieden vom Besitzer**, nachdem der Weg über Proxmox' termproxy gemessen und verworfen wurde

---

## Was gebaut wird

Ein Knopf neben jedem Host — in der Liste und auf der Detailseite — öffnet ein
eigenes Fenster mit einem Terminal, das per SSH auf diesem Host angemeldet ist.
xterm.js im Browser, ein eigener Container dahinter, der nichts anderes tut.

## Warum nicht über Proxmox

Der erste Entwurf ging über Proxmox' `termproxy`: die Konsole holt ein Ticket
über den vorhandenen API-Token, der Browser verbindet direkt zu Proxmox. Kein
eigener Dienst, kein SSH bei uns.

**Gemessen auf `fsn-01`, und daran gescheitert:**

```
access/permissions  → HTTP 200   (Token trägt, aber ohne Sys.Console)
termproxy           → HTTP 500   Not a HASH reference
                                 at /usr/share/perl5/PVE/APIServer/AnyEvent.pm line 978
```

Ein fehlendes Recht gäbe ein sauberes `403`. Dieser Perl-Fehler kommt aus
Proxmox' Konsolen-Code, der eine Sitzung erwartet und einen API-Token vorfindet.
Der Besitzer hat den Weg daraufhin verworfen, statt ihn weiter zu verfolgen.

Dabei fiel noch etwas auf, das über diese Aufgabe hinaus gilt: **der
`app`-Container erreicht keinen Host.** Derselbe Aufruf lief dort in einen
Timeout und erst aus `queue-provisioning` durch. Nur Container im Tunnel sehen
die Hosts — der neue Container muss also dort stehen.

## Der Aufbau

Ein Beiwagen `terminal`, nach dem Vorbild von `kuma-bridge`: eigenes Image, ein
Zweck, keine Datenbank, kein Laravel. Python mit `websockets` und `paramiko` —
dieselbe Sprache wie der bestehende Beiwagen, statt für einen Dienst eine dritte
Laufzeit einzuführen.

Er steht im WireGuard-Tunnel wie `queue-provisioning` und ist aus dem Web über
genau einen Pfad erreichbar, den nginx im `app`-Container durchreicht. Kein
eigener öffentlicher Name, kein eigener Port nach außen.

## Der Ablauf

1. **Klick auf „Terminal".** Eine Livewire-Aktion prüft `hosts.manage` — die
   Aktion, nicht die Seite. Wer einen Host anlegen und entfernen darf, darf auch
   auf ihm arbeiten; ein eigenes Recht wäre eine Unterscheidung ohne Unterschied
   (Entscheidung des Besitzers).

2. **Die App legt ein Ticket in Redis.** 32 Byte Zufall als Schlüssel,
   Lebensdauer **30 Sekunden**, Inhalt:

   | Feld | Woher |
   |---|---|
   | `operator_id` | angemeldeter Betreiber |
   | `host_uuid` | der Host, für den es gilt |
   | `ip` | `hosts.wg_ip` — die Tunneladresse, nie die öffentliche |
   | `user` | `root` |
   | `private_key` | `SecretVault::get('ssh.private_key')` |
   | `fingerprint` | `hosts.ssh_host_key`, gepinnt seit `EstablishSshTrust` |

3. **Ein eigenes Fenster** öffnet `/hosts/{uuid}/terminal?t=<ticket>`. Diese
   Seite gehört uns und zeigt den **ASCII-Vorspann** von CluPilot.

4. **Die Seite öffnet den WebSocket** auf `/terminal/ws`. Das Ticket reist dabei
   als `Sec-WebSocket-Protocol`, **nicht in der Adresszeile** — beim Bau von
   Aufgabe 3 so entschieden: die Adresse eines Upgrade-Antrags schreibt jeder
   Reverse Proxy auf der Strecke mit, und auf dieser Strecke stehen zwei (nginx
   im `app`-Container, Caddy davor), von denen nur einer aus diesem Repo
   konfiguriert wird. Dreißig Sekunden und eine einzige Einlösung begrenzen den
   Schaden — aber ein Geheimnis, das gar nicht erst in ein Protokoll gerät,
   braucht diese Begrenzung nicht.

5. **Der Container löst das Ticket ein.** Er liest es aus Redis und **löscht es
   im selben Zug** — ein Ticket trägt genau eine Sitzung. Danach SSH auf
   `root@<ip>` mit dem Schlüssel, Fingerabdruck geprüft wie in der
   Provisionierung, PTY angefordert, und ab da fließen Bytes in beide
   Richtungen.

6. **Der Vorspann weicht dem Terminal**, sobald das erste Byte da ist — nicht,
   sobald der WebSocket offen ist. Ein Vorspann, der einer Verbindung weicht,
   die noch nicht trägt, ist eine Attrappe.

## Was der Browser nie sieht

Den Schlüssel, die Tunneladresse, den Benutzernamen. Nur ein undurchsichtiges
Ticket, das dreißig Sekunden lebt und beim ersten Gebrauch verfällt. Alles
Übrige steht in Redis und wird vom Container gelesen, nicht vom Browser
mitgegeben.

## Was das kostet — offen benannt

**Ein Container, der gleichzeitig im Tunnel steht und aus dem Web erreichbar
ist, mit einem Schlüssel, der auf jedem Host `root` ist.** Das Ticket ist die
einzige Tür. Diese Angriffsfläche existierte vorher nicht; der Besitzer nimmt
sie nach ausdrücklichem Hinweis in Kauf.

**Die IP-Freigabeliste greift hier nicht.** `RestrictConsoleNetwork` ist
Laravel-Middleware; ein Pfad, den nginx direkt durchreicht, läuft nicht durch
PHP. Für den WebSocket ist das Ticket der alleinige Riegel — einmalig, dreißig
Sekunden, an einen Host und einen Betreiber gebunden. Das ist für diesen Zweck
enger als eine IP-Liste, aber es ist eine Schicht weniger als beim Rest der
Konsole.

**Eine Sitzung ist Root.** Es gibt keine Aufzeichnung dessen, was getippt wird,
und keine Einschränkung der Befehle. Wer den Knopf drücken darf, hat die
Maschine.

## Grenzen, die der Container selbst zieht

- **Leerlauf:** eine Sitzung ohne Ein- und Ausgabe endet nach 15 Minuten.
- **Ende ist Ende:** schließt der WebSocket, wird der SSH-Kanal geschlossen und
  der Prozess beendet. Keine Sitzung überlebt ihr Fenster.
- **Ein Ticket, eine Sitzung:** das Löschen beim Einlösen ist die ganze Regel.
- **Fingerabdruck:** stimmt er nicht, bricht der Aufbau ab — dieselbe Prüfung,
  die die Provisionierung auch macht.

## Was geprüft wird

Automatisiert, in der bestehenden Suite:

1. Ohne `hosts.manage` gibt es kein Ticket.
2. Ein Ticket trägt genau eine Einlösung; die zweite läuft ins Leere.
3. Nach dreißig Sekunden trägt es nicht mehr.
4. Ein Ticket für Host A enthält niemals die Adresse von Host B.
5. Der Schlüssel steht im Ticket-Eintrag in Redis und **niemals** in der
   Antwort an den Browser.
6. Der Knopf erscheint nicht, wenn die Berechtigung fehlt.

Von Hand, weil ein PTY über WebSocket sich in dieser Suite nicht sinnvoll
nachstellen lässt: dass das Terminal wirklich aufgeht, Eingaben ankommen und das
Schließen des Fensters die Sitzung beendet.

## Nicht in diesem Schritt

Ein Terminal auf einer **Kunden-Instanz** (SSH in die VM). Der Besitzer will es,
aber danach — derselbe Container, dieselbe Ticket-Mechanik, andere Zieladresse
und eine andere Berechtigung, weil dort Kundendaten liegen.
