winzik/docs/tcp.md

13 KiB

TCP depuis le navigateur (pont TCP)

Un navigateur ne sait pas ouvrir de socket TCP. Une application (un client SQL...) qui en a besoin utilise $this->engine->tcp() : sur le bureau c'est un socket normal ; dans le navigateur c'est le pont TCP du playground (WebSocket vers TCP).

$c = $this->engine->tcp()->connect('db.example.com', 3306);
$c->on('open', fn () => ...);
$c->on('data', fn (string $octets) => ...);
$c->on('close', fn (?string $raison) => ...);
$c->on('error', fn (string $message) => ...);   // refus, port interdit, pas d'autorisation...
$c->write($octets);

Qui a le droit

  • Le propriétaire de l'application demande l'accès sur la page du projet (studio, « Accès TCP »).
  • L'administrateur (le compte Git davidnurdin) autorise ou refuse dans ses notifications / Administration. Il voit aussi tous les projets.
  • L'autorisation vaut pour un commit précis : une application modifiée doit être autorisée de nouveau.
  • Chaque application a une paire de clés Ed25519. La clé privée est gardée chiffrée sur le compte du propriétaire et signe les tickets ; la plateforme signe « slug | commit | clé publique » à l'autorisation. Le pont ne fait confiance qu'à la clé publique de la plateforme (/api/tcp/public-key) : il vérifie les deux signatures.
  • Le ticket (2 minutes, une connexion) nomme l'hôte et le port. Le port est libre, en TCP comme en UDP : n'importe quel port de 1 à 65535, avec un ticket valide (application approuvée par l'administrateur pour ce commit exact, droit correspondant). Seule une liste de refus s'applique : TCP_DENY_PORTS du pont (défaut 25,465,587 : courrier sortant, spam), plus le port 22 pour un ticket tcp (SSH a son droit ssh). Un port refusé donne l'événement error « port 25 is denied by the platform (global deny list) » et une ligne dans le journal du pont (application, droit, hôte:port, raison). Cette liste globale se règle dans Administration → Ports (stockée, TCP_DENY_PORTS n'est que la valeur par défaut) ; l'administrateur peut aussi, par application, fixer une liste blanche (seuls ces ports, TCP et UDP) et une liste d'interdits. Priorité : liste globale, puis port 22 (ticket tcp), puis liste blanche de l'application (si non vide), puis ses interdits. Le refus nomme le port et la règle (« global deny list », « its deny list », « whitelist of this application »). Ajouter un port coupe les connexions ouvertes qui l'utilisent. Adresses privées / réservées refusées après résolution du nom. Limites par adresse IP.

Le pont : docker/tcpbridge du dépôt jumphp-playground (service tcpbridge, réseau à part, route /tcp du Caddy). project.yaml : tcp_ticket_url (défaut : l'origine de la page dans le navigateur, https://jumphp.net/api/tcp/ticket ailleurs ; la variable d'environnement JUMPHP_TCP_URL l'emporte).

À sauvegarder (administrateur du site)

  • Le droit d'administrateur ne se perd pas avec un fichier : il est lié à ton compte GitHub (User::ADMIN_GITHUB_ID = 50957749, l'id, pas le login : un login renommé et repris par un autre ne donne rien). Garde l'accès à ce compte GitHub (2FA, codes de secours).
  • TOKEN_KEY (deploy/.env du dossier du projet sur le serveur) : à sauvegarder absolument, hors du serveur. Elle sert à chiffrer les jetons Git et les clés privées des applications, et la clé de signature de la plateforme en est dérivée. Perdue ou changée : les jetons ne se déchiffrent plus (tout le monde doit se reconnecter), les clés des applications sont perdues et toutes les autorisations TCP deviennent invalides (à redemander et réautoriser).
  • La base de données (db, volume db, table tcp_grant : état des demandes, clés publiques, clés privées chiffrées) : sauvegarde régulière (mysqldump). Sans elle, les autorisations sont à refaire.
  • Le reste (APP_SECRET, GITHUB_CLIENT_SECRET, DB_PASSWORD...) est dans le même deploy/.env: sauvegarde-le en entier, jamais dans git.

Statistiques, coupure, serveur indépendant

  • Administration (/studio/admin, section « Pont TCP ») : connexions ouvertes (application, cible, adresse, durée, octets, débit), totaux depuis le démarrage (connexions, refus, coupures, ↑ ↓), totaux par application et par adresse, journal. Boutons : Couper une connexion, Bloquer l'application ou l'adresse pour une heure, Débloquer. Les chiffres sont gardés en mémoire par le pont (un redémarrage repart de zéro). Un blocage définitif = refuser l'autorisation de l'application (plus de tickets).
  • Le pont tient ces chiffres et répond à /admin/stats|kill|block|unblock (en-tête X-Admin-Secret, secret partagé TCP_ADMIN_SECRET dans deploy/.env). Caddy ne transmet au pont que /tcp : l'administration n'est pas publique.
  • Serveur indépendant : le pont est un seul fichier PHP (docker/tcpbridge/ du dépôt jumphp-playground, sans dépendance). Sur un autre serveur : docker compose up -d --build avec docker/tcpbridge/compose.yaml (le pont + Caddy pour le certificat wss://), .env : BRIDGE_HOST, PLAYGROUND_URL, TCP_ADMIN_SECRET. Sur le playground (deploy/.env) : TCP_BRIDGE_PUBLIC_URL=wss://<hôte>/tcp (l'adresse que les navigateurs reçoivent avec leur ticket), TCP_BRIDGE_ADMIN_URL=https://<hôte>, et le même TCP_ADMIN_SECRET. Le pont ne fait confiance qu'à la clé publique du playground (/api/tcp/public-key) : il n'a aucun secret. Plusieurs ponts possibles (un par région) avec le même PLAYGROUND_URL.
  • À faire (TODO.md) : encapsuler aussi UDP et ICMP.

Blocages durables, quota, alertes

  • Les blocages et les totaux du pont survivent à un redémarrage (TCP_STATE_FILE, un volume : /data/state.json).
  • Quota de bande passante par application : TCP_QUOTA_MB_PER_HOUR (2048 Mo par heure par défaut sur le playground, 0 = aucun). Dépassé : l'application est bloquée 15 minutes et l'administrateur est prévenu : le pont appelle TCP_ALERT_URL (/api/tcp/alert du playground, avec le secret partagé), la cloche s'allume et la page Administration liste les alertes.

Administration en direct

La section « Pont TCP » de l'Administration se rafraîchit toute seule (2 secondes, sauf onglet caché ou champ en cours de saisie) : connexions ouvertes, débit, demandes de connexion (l'application qui demande, la cible, la réponse : ticket donné ou refusé et pourquoi), journal du pont, le plus récent en haut (chaque ligne nomme l'application, même pour un refus). UDP et ICMP y figurent avec leur portée. Un historique par jour (connexions, refusées, coupées, octets envoyés et reçus ; 60 jours, gardés dans TCP_STATE_FILE) est affiché sous les totaux.

UDP et ICMP (pings)

Quatre droits, chacun demandé par le propriétaire et autorisé par l'administrateur pour un commit précis : tcp (n'importe quel port, sauf la liste de refus), ssh (le client SSH en WebAssembly), udp, icmp.

  • $this->engine->udp()->open($hôte, $port) : les événements de tcp(), mais chaque data est un datagramme et chaque write() en envoie un (DNS, NTP, serveurs de jeu). Le pont : une trame WebSocket = un datagramme, n'importe quelle adresse publique et n'importe quel port, 300 datagrammes par seconde au plus (au-delà : la connexion est coupée et l'administrateur est alerté).
  • $this->engine->icmp()->ping($hôte, 4, 64) : une Task de réponses ['seq' => 1, 'ok' => true, 'ms' => 12.3, 'ttl' => 57, 'from' => '…'], ou ['ok' => false, 'error' => 'ttl', 'hop' => '10.0.0.1'] quand un routeur répond « time to live exceeded » (un traceroute demande avec des TTL 1, 2, 3…). Le pont envoie jusqu'à 4 pings à la fois, 5 par seconde, 200 par connexion. Deux façons, choisies tout seul : en socket brut (extension sockets de PHP, l'image du pont l'a) quand le processus a le droit d'en ouvrir un (root avec NET_RAW ; mesure du temps à la lecture, sans programme externe) et sinon le ping d'iputils de la machine (ICMP_MODE=ping force cette voie). Le pont de jumphp.net tourne en root avec la seule capacité NET_RAW (choix de l'administrateur, 2026-11-08), donc en socket brut : le routeur d'un « time exceeded » est connu. Pourquoi root ? Un socket brut exige CAP_NET_RAW effective ; Docker donne cap_add: [NET_RAW] au jeu de capacités du conteneur mais un processus non-root ne la garde pas à l'exec, et no-new-privileges interdit les capacités de fichier. Les « ping sockets » sans droit (SOCK_DGRAM + IPPROTO_ICMP) répondent aux echo, mais PHP ne sait pas lire la file d'erreurs du noyau (IP_RECVERR) qui seule donne le routeur. Réglage de sécurité : user root dans l'image mais cap_drop: [ALL] + cap_add: [NET_RAW], no-new-privileges:true, système de fichiers en lecture seule, pids_limit, mem_limit, réseau tcp à part, sans secret ni base. Le pont n'exécute aucun code d'utilisateur : il relaie des octets d'après un ticket signé. Risque résiduel : une faille d'exécution dans le pont donnerait uid 0 dans le conteneur, avec NET_RAW (forger des paquets IP/ICMP, sniffer le trafic du réseau tcp du conteneur) mais sans pouvoir écrire hors de /data, monter, charger de module ni gagner de capacité. Les fichiers de /data appartiennent à root (sans DAC_OVERRIDE, root ne peut pas écrire un fichier d'un autre propriétaire : un volume créé par l'ancienne image nobody demande un chown -R 0 /data une fois). Les deux voies donnent les mêmes réponses (ok, ms, ttl, from, ou error : ttl, unreachable, no answer, avec hop et ms).
  • $this->engine->icmp()->trace($hôte, 30) : un traceroute en une Task de sauts ['hop' => 1, 'ip' => '192.168.1.1', 'ms' => 0.4, 'reached' => false] (TTL 1, 2, 3… ; 'ip' => null pour un routeur muet ; fini quand l'hôte répond, ou après 5 sauts muets d'affilée). Une seule connexion (un seul ticket) en mode navigateur ; sur l'ordinateur, le ping du système (-n, jamais de résolution de noms).
  • IPv6 : un nom est résolu en IPv4 d'abord, puis en IPv6 (AAAA) ; une adresse 2606:4700:4700::1111 marche telle quelle pour tcp(), udp(), icmp()->ping() / trace() (le pont lance ping -6, ou un socket ICMPv6). Les adresses privées, locales au lien, uniques locales, de documentation et les formes IPv6 qui cachent une IPv4 (::ffff:a.b.c.d, NAT64, 6to4, Teredo) sont refusées. Il faut que le réseau du pont ait de l'IPv6 pour en sortir (Docker : enable_ipv6 sur son réseau).
  • Alertes (quota dépassé, inondation UDP) : le journal, la cloche du playground (TCP_ALERT_URL) et, si TCP_ALERT_WEBHOOK est défini sur le pont, un POST JSON {"text": "…", "content": "…", "source": "jumphp-tcpbridge", "at": "2026-11-08T12:00:00+00:00"} vers cette adresse (Slack, Mattermost, Discord et ntfy lisent text / content ; pour un courriel, pointez un petit script ou un service qui en envoie un). Pas de client SMTP dans le pont : une dépendance et un mot de passe de plus pour un service sans état.
  • Les quotas de bande passante par heure : par application (TCP_QUOTA_MB_PER_HOUR), par adresse (TCP_QUOTA_IP_MB_PER_HOUR) et par compte, c'est-à-dire le propriétaire des applications (TCP_QUOTA_ACCOUNT_MB_PER_HOUR) : dépassé, l'application / l'adresse / le compte est bloqué 15 minutes et l'administrateur est prévenu. L'administration peut aussi bloquer un compte.

Utiliser le réseau de l'utilisateur : le JumPHP runtime

Le pont du serveur ne voit que ce que le serveur voit. Pour joindre une base du réseau local, derrière un VPN, ou un serveur qui n'ouvre qu'à l'adresse de la personne, l'application peut passer par le JumPHP runtime, un petit programme sur l'ordinateur de la personne (docs/runtime.md, protocole : docs/runtime-protocol.md). Le réglage net_mode de project.yaml (ou JUMPHP_NET_MODE, page ou environnement) choisit : auto (défaut : le runtime quand il est installé et que la personne a autorisé l'appli, sinon le pont du serveur), server (toujours le serveur), local (le runtime, ou l'erreur « the JumPHP runtime is not available (state: …) »). Le ticket est toujours demandé au serveur (l'administrateur doit avoir approuvé l'appli) : seule l'adresse ouverte ensuite change. Il faut l'extension jumphp/runtime (sans elle, le serveur est toujours utilisé).

Les crashs du moteur

Quand le moteur du navigateur s'arrête (« The engine crashed: … »), la page envoie un rapport à jumphp.net (/api/crash) : l'application, la version, l'adresse, la trace et le journal des 150 dernières lignes (sorties de PHP, erreurs de la page). L'administrateur les lit dans Administration → Rapports de crash (détail : trace + journal) et par le MCP (list_crash_reports, get_crash_report, delete_crash_report) pour reprendre plus tard. Exemple de cause trouvée ainsi : « missing function: getcontext » = une Fiber dans le navigateur (PHP en WebAssembly n'en a pas : utilisez des générateurs).

Exemples pas à pas

  • docs/tuto-tcp.md : apps/hello-tcp, un PING à un Redis par une connexion TCP.
  • docs/tuto-ssh.md : apps/hello-ssh, la même chose à travers un serveur SSH (sélecteur de clé, trousseau).