JumPHP runtime : protocole et modèle de sécurité (spécification)
Le JumPHP runtime est un petit programme qui tourne sur l'ordinateur de la personne (icône dans la zone de notification, démarré avec
la session) et qui permet aux applications JumPHP qui tournent dans le navigateur (jumphp.net, play.jumphp.net) de se connecter en
TCP / UDP / ICMP / SSH depuis l'adresse IP et le réseau de la personne (réseau local, VPN, serveur qui n'ouvre qu'à son adresse), avec son
autorisation. Sans lui, ces connexions passent par le pont TCP du serveur jumphp.net (docker/tcpbridge du playground), qui ne voit que
ce que le serveur voit. Ce document est la référence commune du démon (apps/runtime), du client du moteur (extensions/runtime) et des docs.
Vue d'ensemble
page de l'appli (https://play.jumphp.net/<slug>/play/)
│ 1. demande un TICKET à jumphp.net (POST /api/tcp/ticket) : l'administrateur a approuvé cette appli, ce commit, ce droit
│ 2. ouvre ws://127.0.0.1:47820/v1 (le runtime) et envoie create {meta:{tcp_ticket}}
▼
JumPHP runtime (127.0.0.1) ── vérifie origine, ticket, autorisation de la personne ──► TCP vers host:port, depuis ce PC
Le ticket reste celui du serveur : les deux portes doivent être ouvertes (l'administrateur de jumphp.net a approuvé l'application pour cette
version exacte du code, ET la personne a autorisé l'application sur son ordinateur). Le runtime ne parle jamais à jumphp.net sauf pour lire la
clé publique de la plateforme (GET https://jumphp.net/api/tcp/public-key, mise en cache) et chercher ses mises à jour.
Point d'entrée
ws://127.0.0.1:47820/v1(etws://[::1]:47820/v1). Jamais une autre interface. Port par défaut 47820 ; s'il est pris, 47821 à 47829 (le client les essaie dans l'ordre, 400 ms chacun). Réglage~/.config/jumphp-runtime/config.json(port,origins).- Protocole identique à celui du pont du serveur (
docker/tcpbridge/bridge.phpdu playground,php-wasm-network.js) :helloà l'ouverture,createavecmeta.tcp_ticket,roomquand la cible est jointe, trames binaires[to] octetsdans les deux sens,ping/pong,peer-leave,error {code, message}, et le mode brut (?raw=1: les trames binaires sont les octets, pour le client SSH WebAssembly). Les clients du moteur (TcpConnection,SshConnection,UdpConnection,Icmp) n'ont donc que l'adresse du pont à changer.
Sécurité (le démon n'accepte pas n'importe qui)
- Interface : liaison à 127.0.0.1 / ::1 uniquement.
- Hôte : l'en-tête
Hostdoit être127.0.0.1:<port>,[::1]:<port>oulocalhost:<port>(contre le DNS rebinding) ; sinon 421. - Origine : l'en-tête
Originest obligatoire et doit être dans la liste blanche :https://jumphp.net,https://play.jumphp.netpar défaut ; la personne peut en ajouter (un site JumPHP à elle) dans la fenêtre du runtime, jamais*. Sans origine (un programme local) ou origine inconnue : 403, rien n'est exécuté, la tentative est journalisée (visible dans la fenêtre). - Ticket : comme le pont du serveur,
createexige un ticket valide : signature Ed25519 de l'appli + signature de la plateforme de « slug|commit|clé publique » (clé de la plateforme lue sur/api/tcp/public-key), non expiré (120 s). Un ticket dit l'appli, la cible (hôte, port), le droit (tcp,ssh,udp,icmp). Le ticket ne dit pas si la personne est d'accord : c'est l'étape suivante. - Autorisation de la personne (boîte de dialogue native du système, jamais dans la page) :
- première fois qu'une origine + appli demande : « Le site play.jumphp.net veut utiliser votre réseau pour l'application jumphpsql. Autoriser ? » (Autoriser toujours / Cette fois / Refuser) ;
- première fois qu'une appli autorisée vise une adresse privée ou locale (10.x, 172.16-31.x, 192.168.x, 127.x, ::1, fc00::/7, fe80::/10, noms qui
y résolvent) ou un port inhabituel pour le droit (
Targets::USUAL_PORTS: bases de données pourtcp, 22 pourssh, DNS / NTP... pourudp; ce n'est PAS une limite : tout port 1-65535 est permis, la politique de ports du serveur étant une liste de refusTCP_DENY_PORTS, défaut 25, 465, 587, voir docs/tcp.md) : une confirmation par cible (« jumphpsql veut joindre 192.168.1.10:3306 »). - Les autorisations « toujours » sont gardées dans
grants.json(origine, slug, droits, cibles), révocables une par une ou toutes d'un coup (fenêtre du runtime, menu de l'icône). Un refus est gardé 10 minutes (pas d'harcèlement par boîtes de dialogue). - Pas de boîte ouverte plus d'une à la fois ; 30 s sans réponse = refus.
- Limites : 32 connexions ouvertes, 10 créations par minute et par origine, 1 h de vie maximale par connexion, 15 min sans trafic ; frames de 64 Ko. Le trafic n'est jamais enregistré, seuls l'origine, l'appli, la cible, l'heure, le volume le sont (journal tournant, fenêtre du runtime).
- Pas d'autre fonction : aucune commande locale, aucun accès aux fichiers, aucune écoute (le démon ne fait que connecter vers l'extérieur, jamais
bindpour les pages). Les mises à jour sont signées (comme celles de l'IDE) et jamais automatiques sans clé valide. - Navigateurs : Chrome / Edge / Firefox acceptent
ws://127.0.0.1depuis une page https (adresse « potentiellement fiable ») ; Chrome peut demander à la personne l'autorisation « Accéder aux appareils du réseau local » (Local Network Access) la première fois : le guide du moteur l'explique. Safari bloque ce contenu mixte : le client retombe sur le pont du serveur (voir ci-dessous).
Messages propres au runtime (en plus du protocole du pont)
| Sens | Message | Rôle |
|---|---|---|
| runtime → page | {"t":"hello","v":1,"runtime":"0.1.0","os":"linux","granted":false} |
à l'ouverture : version, système, l'origine est-elle déjà autorisée pour au moins une appli |
| page → runtime | {"t":"pair","app":"jumphpsql","title":"jumphpsql","scope":"tcp"} |
demande l'autorisation de la personne pour cette appli (dialogue natif) sans ouvrir de connexion |
| runtime → page | {"t":"paired","app":"jumphpsql","granted":true,"always":true} |
la réponse (refus : granted:false) |
| page → runtime | {"t":"status"} → {"t":"status","connections":2,"granted":["jumphpsql"]} |
pour le voyant du client |
| runtime → page | `{"t":"error","code":"origin | ticket |
Notifications
Le runtime Android (apps/runtime-android) sait aussi afficher des notifications push : messages notify-subscribe, notify-unsubscribe,
notify-status (réponses notify-subscribed, notify-unsubscribed, notify-status), hello avec "notify":true. Le ticket est un ticket
ordinaire de /api/tcp/ticket de scope notify, sans cible ; il n'ouvre aucune connexion (le runtime refuse un create avec ce ticket).
Le consentement est une question native (Autoriser / Refuser, 30 s sans réponse = refus, refus gardé 10 min, une question à la fois), gardé par
application et révocable dans l'écran principal. Le runtime de bureau répond {"t":"error","code":"unsupported"}.
Le contrat complet (messages, API du serveur, message FCM, accusés) : docs/notifications.md.
Côté moteur (client)
- Extension
extensions/runtime(packagejumphp/runtime,$engine->runtime()), classeJumPHP\Runtime\RuntimeClient:state()=unknown|checking|missing(rien n'écoute : pas installé ou pas lancé) |running(répond, pas encore autorisé) |ready(autorisé pour cette appli) |refused|unsupported(navigateur qui bloque) ;check()(Task),pair(), événementchange. - Mode réseau : réglage
JUMPHP_NET_MODE/project.yaml net_mode=auto(défaut : le runtime s'il estready, sinon le pont du serveur) |server|local(le runtime ou une erreur claire).TcpConnection,SshConnection,UdpConnection,Icmpdemandent le ticket au serveur comme aujourd'hui, puis ouvrentbridge(adresse du serveur) ouws://127.0.0.1:47820/v1selon le mode. - Widget
RuntimeBadge(JumPHP\Gui) : voyant vert (le runtime est installé et autorisé : « Réseau local actif »), orange (installé, il faut autoriser), rouge (pas installé / pas lancé : cliquer guide la personne : télécharger pour son système, installer, lancer, autoriser) et gris (le pont du serveur suffit). Le guide pointe vershttps://jumphp.net/runtimeet les releases degit.jumphp.net/jumphp/jumPhp(runtime-v<version>). - Rien de tout ça n'existe hors du navigateur : sur le bureau l'appli a déjà son réseau (
Platform::isWasm()faux,RuntimeClienttoujoursunsupported).
Fichiers du démon
~/.config/jumphp-runtime/ (Windows : %APPDATA%\jumphp-runtime\) : config.json (port, origines ajoutées, démarrage avec la session),
grants.json (autorisations), log.jsonl (journal tournant, 2 Mo). Aucun secret, aucune clé privée de la personne.