Co-Authored-By: Claude Sonnet 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_018nX3d1jqkxbS2Bhas8tTzM
109 lines
13 KiB
Markdown
109 lines
13 KiB
Markdown
# 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).
|
|
|
|
```php
|
|
$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).
|