Tutorial: una connessione attraverso SSH, passo dopo passo

Il progetto di esempio apps/hello-ssh raggiunge un server Redis che solo un server SSH (un bastione) può raggiungere: ssh -W host:port, il flusso della connessione è il flusso verso Redis. Sul computer è l'ssh del sistema; nel browser, il vero client OpenSSH compilato in WebAssembly, collegato al tuo PHP tramite una pipe.

1. Creare l'applicazione

bin/jumphp gui:new mon-ssh "Mon SSH" && bin/jumphp install mon-ssh

2. La finestra

forms/MainForm.form.yaml (copia apps/hello-ssh/forms/MainForm.form.yaml): il server SSH (sshHost, sshPort, sshUser), un pulsante « Choose a key file… » (chooseKey), la passphrase della chiave (passphrase), la destinazione vista dal bastione (host, port), un pulsante ping, status, result.

3. La chiave: il selettore di file

Un browser non ha una cartella ~/.ssh: si chiede il file alla persona. FilePicker::open() funziona sul computer E nel browser (chiamalo da un clic); il file scelto arriva a un percorso che si legge e poi si cancella. Lo si conserva nel portachiavi dell'applicazione ($this->engine->sshKeyring(): il ruolo di un agente, che il browser non ha).

public function onChooseKey(Button $sender): void
{
    FilePicker::open(['title' => 'SSH private key'])->then(function (?string $file): void {
        if ($file === null) { return; }                                   // annulé
        $text = (string)file_get_contents($file);
        unlink($file);
        $this->engine->sshKeyring()->add(basename($file), $text, $this->passphrase->text);   // nom, clé, phrase secrète
        $this->keyState->text = 'Keys: ' . implode(', ', $this->engine->sshKeyring()->names());
    });
}

La chiave resta nell'archiviazione dell'applicazione (var/ssh_keyring.json: IndexedDB nel browser, la cartella dei dati sul computer) e non viene mai inviata al server: va nella memoria del client SSH. Ogni connessione propone tutte le chiavi del portachiavi, come un agente.

4. Connettersi

$options = ['sshHost' => 'bastion.exemple.com', 'sshPort' => 22, 'sshUser' => 'moi', 'sshKeys' => $this->engine->sshKeyring()->all()];
$connection = $this->engine->ssh()->connect('127.0.0.1', 6379, $options);      // 127.0.0.1:6379 vu depuis le bastion
$connection->on('open', fn () => $connection->write("PING\r\n"));
$connection->on('data', fn (string $bytes) => $this->result->text = trim($bytes));
$connection->on('error', fn (string $m) => $this->result->text = $m);          // « Permission denied (publickey) », « Could not resolve hostname »...
$connection->on('knownHosts', fn (string $text) => $this->engine->storage->writeJson('known_hosts.json', ['text' => $text]));   // l'empreinte du serveur, gardée

Gli stessi eventi di tcp(). Per il codice che accetta un Tcp (come il client MySQL di apps/jumphpsql): $this->engine->ssh()->via($options) ha lo stesso connect($host, $port, $timeout). Le opzioni: docs/ssh-wasm.md.

5. Testare

bin/jumphp test mon-ssh      # le trousseau, les champs manquants, un ssh qui n'atteint pas son serveur (le message dit pourquoi)
bin/jumphp shot mon-ssh
bin/jumphp run mon-ssh       # sur l'ordinateur : le ssh du système (votre agent et ~/.ssh marchent aussi)

6. Il browser: due diritti

bin/jumphp build mon-ssh && bin/jumphp serve mon-ssh

Nel browser, due livelli passano per il bridge TCP di jumphp.net, che accetta solo le applicazioni autorizzate: il client SSH (WebAssembly) si connette al bastione (porta 22 o un'altra) → serve il diritto SSH. (Un client SQL che parla direttamente con un database ha bisogno del diritto TCP.) Studio → il progetto → Accès SSH → « Demander l'accès SSH »; l'amministratore lo autorizza per il commit pubblicato.

Il diritto SSH è più ampio (qualsiasi porta di un indirizzo pubblico, mai un indirizzo privato): l'amministratore lo concede solo a codice che ha esaminato. Statistiche, registro, interruzione e blocco: Administration → Pont TCP.

7. Verificare nel browser

Pagina del progetto su jumphp.net: scegli la tua chiave (si apre il selettore di file del tuo computer), indica il bastione e la destinazione, clicca « Send PING through SSH »: The server answered: +PONG. Nei primi secondi compare « The SSH session is starting… »: il client SSH si avvia in un Web Worker (un file da 3,8 MB caricato su richiesta).

Come funziona (due wasm collegati da una pipe), la sicurezza e la compilazione di OpenSSH: docs/ssh-wasm.md. Il primo tutorial: docs/tuto-tcp.md.