@imenam/self-register-proxy 1.0.43 → 1.0.45

package/README.md

@@ -472,10 +472,18 @@ Le proxy charge automatiquement le fichier `.env` s'il existe (voir `.env.exampl
 |----------|--------|-------------|
 | `PROXY_NAME` | `Proxy Server` | Nom affiché sur la page d'accueil |
 | `PROXY_PORT` | `3000` | Port d'écoute du proxy |
+| `PROXY_HOST` | *(toutes les interfaces)* | Adresse d'écoute. `127.0.0.1` confine le proxy — dashboard et terminal compris — à la machine locale. Voir [Sécurité](#sécurité). |
+| `PROXY_INTERNAL_PORT_START` | `4000` | Premier port attribuable aux applications enregistrées |
+| `PROXY_INTERNAL_PORT_END` | `5000` | Dernier port attribuable |
+| `PROXY_ADMIN_PASSWORD` | *(aucun)* | Mot de passe du dashboard. **Sans lui, le dashboard, son terminal et les routes shell ne sont pas protégés.** |
+| `PROXY_SESSION_SECRET` | *(généré)* | Clé de signature des sessions. **Obligatoire** dès que `PROXY_ADMIN_PASSWORD` est défini, sinon le proxy sort en `exit(1)`. |
 | `HEALTH_CHECK_INTERVAL` | `30000` | Intervalle du health check polling (ms) |
 | `HEALTH_CHECK_TIMEOUT` | `5000` | Timeout pour chaque health check (ms) |
 | `HEALTH_CHECK_GRACE_PERIOD` | `60000` | Période de grâce pour les nouveaux serveurs (ms) |
 | `PROXY_CONFIG_DIR` | `.` | Dossier de stockage des configurations (meta-configs.json) |
+| `PROXY_TERMINAL_CWD` | `$HOME` / `%USERPROFILE%` | Répertoire de travail du terminal en ligne |
+| `PROXY_TERMINAL_COMMAND` | *(shell par défaut)* | Commande lancée par le terminal en ligne |
+| `PROXY_OPENCODE_CLEAN_UP` | *(aucune)* | Commande exécutée par `POST /proxy/cleanup` |
 
 ### Variables pour les applications clientes
 
@@ -484,18 +492,69 @@ Le proxy charge automatiquement le fichier `.env` s'il existe (voir `.env.exampl
 | `PROXY_URL` | `http://localhost:3000` | URL du proxy (pour les apps) |
 | `APP_PATH` | `/example` | Chemin de l'application |
 | `APP_NAME` | `Example App` | Nom de l'application |
+| `APP_GROUP` | *(aucun)* | Groupe d'affichage dans le dashboard. Absent : l'application apparaît sous « Non groupées ». |
 
-## Plage de ports
+## Sécurité
 
-Par défaut, le proxy attribue des ports entre **4000** et **5000** (1000 ports disponibles).
+**Le dashboard n'est pas qu'une liste de liens.** Il sert un terminal interactif
+(`/proxy/terminal`, un vrai PTY sur la machine) et deux routes qui exécutent du
+shell : `POST /proxy/kill-port` et `POST /proxy/cleanup`. Elles sont derrière
+`requireAuth` — **qui laisse tout passer quand `PROXY_ADMIN_PASSWORD` n'est pas
+défini** (rétrocompatibilité historique). Le `verifyClient` du WebSocket du
+terminal a la même porte ouverte.
 
-Pour modifier cette plage, éditez `proxy.js` :
+Le proxy écoute par défaut sur **toutes les interfaces**. Sans mot de passe, il
+offre donc un shell sans identifiants à quiconque atteint son port depuis le
+réseau. Deux postures saines, à choisir explicitement :
 
-```javascript
-const INTERNAL_PORT_START = 4000;
-const INTERNAL_PORT_END = 5000;
+```bash
+# Poste local : rien n'est exposé hors de la machine.
+PROXY_HOST=127.0.0.1
+
+# Accès distant / tunnel : le dashboard est protégé.
+PROXY_ADMIN_PASSWORD=...
+PROXY_SESSION_SECRET=...   # 32 octets hex ; obligatoire avec le mot de passe
 ```
 
+Le proxy affiche au démarrage l'adresse à laquelle il se lie et avertit
+bruyamment quand ces deux protections manquent toutes les deux.
+
+**HSTS.** Jusqu'à la 1.0.43, un en-tête `Strict-Transport-Security` était émis dès
+qu'un mot de passe était défini, même sur des réponses servies en clair : le
+navigateur forçait ensuite `https://` sur cette origine pour un an, et le proxy —
+qui ne sert pas de TLS — répondait `ERR_SSL_PROTOCOL_ERROR`. Depuis la 1.0.44,
+HSTS n'est posé que sur une requête réellement en HTTPS (`req.secure`, ou un
+`X-Forwarded-Proto: https` de terminaison TLS). Le cookie de session suit la même
+règle pour son attribut `Secure`, qui empêchait sinon toute connexion sur un
+domaine servi en clair. Si votre navigateur a mémorisé l'ordre, purgez l'origine
+dans `chrome://net-internals/#hsts`.
+
+## Plage de ports
+
+Par défaut, le proxy attribue des ports entre **4000** et **5000** (1000 ports
+disponibles). Depuis la 1.0.44 la plage se règle par variables d'environnement,
+sans toucher au code :
+
+```bash
+PROXY_INTERNAL_PORT_START=5200
+PROXY_INTERNAL_PORT_END=5400
+```
+
+Une valeur invalide, ou une plage inversée, est ignorée au profit des valeurs par
+défaut, avec un avertissement au démarrage.
+
+**Faites-le si deux proxys tournent sur la même machine.** Chaque proxy gère sa
+plage pour lui seul et ignore l'existence de l'autre : avec la même plage des deux
+côtés, le second peut attribuer à une application un port déjà occupé par une
+application du premier. Sa sonde de santé interroge alors le service de l'autre,
+qui répond — la route ne meurt jamais et les requêtes partent au mauvais endroit.
+
+> **Correctif 1.0.44 — sonde de disponibilité.** Elle se contentait d'essayer de
+> se lier au port. Sous Windows, lier `127.0.0.1:<port>` **réussit** alors qu'un
+> autre process écoute déjà sur `0.0.0.0:<port>` : un port occupé était déclaré
+> libre, puis attribué. La sonde tente désormais aussi une **connexion**, ce qui
+> donne la même réponse sur tous les systèmes.
+
 ## Fonctionnalités
 
 - **Attribution sécurisée des ports** : utilisation d'un mutex pour éviter les conflits lors d'enregistrements simultanés
@@ -514,9 +573,16 @@ Le format des logs inclut la date, l'heure, le PID et le tag `[PROXY]`.
 
 ## Limitations
 
-- Les routes sont stockées en mémoire (perdues au redémarrage du proxy)
+- Les routes sont stockées en mémoire (perdues au redémarrage du proxy), et **les
+  applications ne se réenregistrent pas d'elles-mêmes** : après un redémarrage du
+  proxy, il faut relancer chaque application
 - Pas de persistance des enregistrements
-- Pas d'authentification sur l'API de registration
+- `POST /proxy/register` et `DELETE /proxy/unregister` sont ouvertes sans mot de
+  passe, mais **restreintes à localhost**. Le dashboard et ses routes shell, eux,
+  ne sont protégés que par `PROXY_ADMIN_PASSWORD` — voir [Sécurité](#sécurité)
+- `group` est un **libellé d'affichage**, pas un espace de noms : il ne dédoublonne
+  pas les chemins. Deux applications au même chemin restent en conflit (409), quel
+  que soit leur groupe
 - Les applications doivent implémenter `GET /proxy/health` pour ne pas être désenregistrées automatiquement
 
 ## Licence

package/config.js

@@ -2,8 +2,45 @@ const crypto = require('crypto');
 
 const PROXY_PORT = process.env.PROXY_PORT || 3000;
 const PROXY_NAME = process.env.PROXY_NAME || 'Proxy Server';
-const INTERNAL_PORT_START = 4000;
-const INTERNAL_PORT_END = 5000;
+
+/**
+ * Interface d'écoute. Non définie = comportement historique : Express écoute sur
+ * **toutes** les interfaces (0.0.0.0), le dashboard et son terminal PTY sont donc
+ * joignables depuis le réseau. `PROXY_HOST=127.0.0.1` restreint l'écoute à la
+ * boucle locale — c'est ce que pose un superviseur qui démarre un proxy sans
+ * `PROXY_ADMIN_PASSWORD`.
+ */
+const PROXY_HOST = process.env.PROXY_HOST || undefined;
+
+/**
+ * Plage des ports attribués aux applications enregistrées.
+ *
+ * Historiquement codée en dur à 4000-5000, ce qui rendait impossible de faire
+ * cohabiter deux proxys sur une même machine sans qu'ils se disputent les mêmes
+ * ports. Elle est désormais configurable ; **les valeurs par défaut ne changent
+ * pas**, et une valeur invalide est ignorée au profit du défaut.
+ */
+function readPortBound(name, fallback) {
+  const raw = process.env[name];
+  if (raw === undefined || raw === '') return fallback;
+  const value = Number.parseInt(raw, 10);
+  if (!Number.isInteger(value) || value < 1 || value > 65535) {
+    console.warn(`[CONFIG] ${name}="${raw}" invalide — valeur par défaut ${fallback} conservée.`);
+    return fallback;
+  }
+  return value;
+}
+
+let INTERNAL_PORT_START = readPortBound('PROXY_INTERNAL_PORT_START', 4000);
+let INTERNAL_PORT_END = readPortBound('PROXY_INTERNAL_PORT_END', 5000);
+if (INTERNAL_PORT_START > INTERNAL_PORT_END) {
+  console.warn(
+    `[CONFIG] Plage de ports internes inversée (${INTERNAL_PORT_START}-${INTERNAL_PORT_END}) — ` +
+    'retour aux valeurs par défaut 4000-5000.'
+  );
+  INTERNAL_PORT_START = 4000;
+  INTERNAL_PORT_END = 5000;
+}
 const HEALTH_CHECK_INTERVAL = process.env.HEALTH_CHECK_INTERVAL || 30000;
 const HEALTH_CHECK_TIMEOUT = process.env.HEALTH_CHECK_TIMEOUT || 5000;
 const HEALTH_CHECK_GRACE_PERIOD = process.env.HEALTH_CHECK_GRACE_PERIOD || 60000;
@@ -20,6 +57,7 @@ const MINIMAL_DASHBOARD = process.argv.includes('--minimal-dashboard');
 module.exports = {
   PROXY_PORT,
   PROXY_NAME,
+  PROXY_HOST,
   INTERNAL_PORT_START,
   INTERNAL_PORT_END,
   HEALTH_CHECK_INTERVAL,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/self-register-proxy",
-  "version": "1.0.43",
+  "version": "1.0.45",
   "description": "Dynamic reverse proxy with self-registration API - applications can register themselves and receive an automatically assigned port",
   "main": "proxy-client.js",
   "bin": {

package/proxy.js

@@ -14,6 +14,7 @@ setupLogging('PROXY');
 const {
   PROXY_PORT,
   PROXY_NAME,
+  PROXY_HOST,
   INTERNAL_PORT_START,
   INTERNAL_PORT_END,
   HEALTH_CHECK_INTERVAL,
@@ -42,6 +43,26 @@ const dashboardRoutes = require('./routes/dashboard');
 
 const app = express();
 
+/**
+ * Vrai si la requête est arrivée en HTTPS — directement, ou via un terminaison
+ * TLS en amont qui l'annonce (`X-Forwarded-Proto`, posé par ngrok, nginx, etc.).
+ */
+const isHttpsRequest = (req) =>
+  req.secure || String(req.headers['x-forwarded-proto'] || '').split(',')[0].trim() === 'https';
+
+/**
+ * HSTS **uniquement sur une requête réellement servie en HTTPS**.
+ *
+ * Avant : HSTS était activé dès qu'un mot de passe était défini, quel que soit le
+ * protocole. Un `http://127.0.0.1:3000` renvoyait donc un `Strict-Transport-Security`
+ * que le navigateur mémorisait pour un an : toute visite suivante était forcée en
+ * `https://`, et le proxy — qui ne sert pas de TLS — répondait `ERR_SSL_PROTOCOL_ERROR`.
+ * Le même piège est franchement bloquant sur un domaine servi en clair.
+ *
+ * Un en-tête HSTS émis sur une réponse HTTP est de toute façon ignoré par les
+ * navigateurs conformes (RFC 6797 §7.2) : le restreindre à HTTPS ne retire donc
+ * aucune protection réelle aux déploiements sous TLS.
+ */
 app.use(helmet({
   contentSecurityPolicy: {
     directives: {
@@ -53,10 +74,16 @@ app.use(helmet({
       imgSrc: ["'self'", "data:", "https://i.ytimg.com"],
     },
   },
-  hsts: ADMIN_PASSWORD ? { maxAge: 31536000, includeSubDomains: true } : false,
+  hsts: false,
   referrerPolicy: { policy: 'same-origin' },
 }));
 
+const hstsMiddleware = helmet.hsts({ maxAge: 31536000, includeSubDomains: true });
+app.use((req, res, next) => {
+  if (ADMIN_PASSWORD && isHttpsRequest(req)) return hstsMiddleware(req, res, next);
+  next();
+});
+
 const isLocalRequest = (req) => {
   const ip = req.ip || req.connection?.remoteAddress || '';
   return ip === '127.0.0.1' || ip === '::1' || ip === '::ffff:127.0.0.1';
@@ -97,11 +124,15 @@ app.use(routingMiddleware);
 // DÉMARRAGE DU SERVEUR
 // ============================================
 
-const server = app.listen(PROXY_PORT, () => {
+// `PROXY_HOST` non défini = comportement historique (toutes les interfaces).
+const listenArgs = PROXY_HOST ? [PROXY_PORT, PROXY_HOST] : [PROXY_PORT];
+
+const server = app.listen(...listenArgs, () => {
   console.log('='.repeat(50));
   console.log(`🚀 ${PROXY_NAME}`);
   console.log('='.repeat(50));
   console.log(`Listening on port ${PROXY_PORT}`);
+  console.log(`Bind address: ${PROXY_HOST || '0.0.0.0 (toutes les interfaces)'}`);
   console.log(`Internal ports range: ${INTERNAL_PORT_START}-${INTERNAL_PORT_END}`);
   console.log(`Health check interval: ${HEALTH_CHECK_INTERVAL}ms`);
   console.log(`Health check grace period: ${HEALTH_CHECK_GRACE_PERIOD}ms`);
@@ -109,6 +140,12 @@ const server = app.listen(PROXY_PORT, () => {
 
   if (!ADMIN_PASSWORD) {
     console.log('⚠️  WARNING: ADMIN_PASSWORD is not set — web interface is unprotected');
+    console.log('⚠️  Le dashboard expose un terminal PTY et les routes kill-port / cleanup,');
+    console.log('⚠️  qui exécutent du shell sans authentification.');
+    if (!PROXY_HOST) {
+      console.log('⚠️  Écoute sur toutes les interfaces : cette surface est joignable depuis le réseau.');
+      console.log('⚠️  Posez PROXY_ADMIN_PASSWORD, ou PROXY_HOST=127.0.0.1 pour la boucle locale.');
+    }
   } else {
     console.log('🔒 Web interface protected by admin password');
     console.log('🔒 Session secret configured');

package/routes/dashboard.js

@@ -44,7 +44,7 @@ router.post('/proxy/login', (req, res) => {
 
   if (ADMIN_PASSWORD && safeEqual(password, ADMIN_PASSWORD)) {
     const token = createSession();
-    setSessionCookie(res, token);
+    setSessionCookie(res, token, req);
     return res.redirect('/');
   }
 

package/services/auth.js

@@ -89,9 +89,27 @@ function isValidSession(token) {
   return true;
 }
 
-function setSessionCookie(res, token) {
+/**
+ * L'attribut `Secure` n'est posé que si la requête est **réellement** en HTTPS.
+ *
+ * Il l'était auparavant dès qu'un mot de passe était configuré : sur un domaine
+ * servi en clair, le navigateur refusait alors d'enregistrer le cookie et la
+ * connexion échouait en boucle, sans message. (En `http://localhost` le problème
+ * ne se voyait pas : les navigateurs y traitent l'origine comme sûre.)
+ *
+ * `req` est optionnel pour rester rétrocompatible avec les appelants existants,
+ * qui retrouvent alors l'ancien comportement.
+ */
+function isSecureRequest(req) {
+  if (!req) return !!ADMIN_PASSWORD;
+  if (req.secure) return true;
+  const forwarded = String((req.headers && req.headers['x-forwarded-proto']) || '');
+  return forwarded.split(',')[0].trim() === 'https';
+}
+
+function setSessionCookie(res, token, req) {
   const signed = signToken(token);
-  const secure = ADMIN_PASSWORD ? '; Secure' : '';
+  const secure = isSecureRequest(req) ? '; Secure' : '';
   res.setHeader('Set-Cookie', `proxy_session=${encodeURIComponent(signed)}; HttpOnly; SameSite=Lax; Path=/${secure}`);
 }
 

package/services/portManager.js

@@ -14,20 +14,67 @@ function isLocalTarget(target) {
   }
 }
 
+/** Délai au-delà duquel une tentative de connexion locale est abandonnée. */
+const CONNECT_PROBE_TIMEOUT = 300;
+
 /**
- * Vérifie si un port est réellement libre au niveau OS
+ * Vrai si l'OS nous laisse écouter sur ce port.
+ *
+ * Attention : ce test **ne suffit pas seul** (voir `isSomeoneListening`).
  */
-function isPortFree(port) {
+function canBind(port, host) {
   return new Promise((resolve) => {
     const server = net.createServer();
     server.once('error', () => resolve(false));
     server.once('listening', () => {
       server.close(() => resolve(true));
     });
-    server.listen(port);
+    if (host) server.listen(port, host);
+    else server.listen(port);
   });
 }
 
+/**
+ * Vrai si **quelqu'un accepte déjà** des connexions sur `host:port`.
+ *
+ * Pourquoi cette seconde sonde : sous Windows, lier `127.0.0.1:<port>` **réussit**
+ * alors qu'un process tiers écoute déjà sur `0.0.0.0:<port>` — le bind d'une
+ * adresse précise n'entre pas en conflit avec un bind générique d'un autre
+ * process. Le test de bind seul déclarait donc libre un port occupé, et le proxy
+ * attribuait ce port à une application ; sa sonde de santé interrogeait ensuite
+ * le service de l'autre process, qui répondait, et la route ne mourait jamais.
+ * Sous Linux le même bind échoue en `EADDRINUSE` : le défaut était invisible
+ * hors Windows.
+ *
+ * Une tentative de connexion, elle, répond la même chose partout. Un timeout est
+ * traité comme « occupé » : en local, une connexion sans réponse n'est pas normale.
+ */
+function isSomeoneListening(port, host = '127.0.0.1', timeoutMs = CONNECT_PROBE_TIMEOUT) {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    const done = (value) => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(value);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once('connect', () => done(true));
+    socket.once('timeout', () => done(true));
+    // ECONNREFUSED (personne n'écoute) et les autres erreurs : port utilisable.
+    socket.once('error', () => done(false));
+    socket.connect(port, host);
+  });
+}
+
+/**
+ * Vérifie si un port est réellement libre au niveau OS : personne ne peut s'y
+ * lier **et** personne n'y répond. Les deux conditions sont nécessaires.
+ */
+async function isPortFree(port) {
+  if (!(await canBind(port))) return false;
+  return !(await isSomeoneListening(port));
+}
+
 /**
  * Trouve le prochain port disponible et le réserve atomiquement
  * DOIT être appelé avec le mutex acquis
@@ -79,4 +126,12 @@ function findRouteForPath(requestPath) {
   return null;
 }
 
-module.exports = { isLocalTarget, isPortFree, getNextAvailablePort, releasePort, findRouteForPath };
+module.exports = {
+  isLocalTarget,
+  canBind,
+  isSomeoneListening,
+  isPortFree,
+  getNextAvailablePort,
+  releasePort,
+  findRouteForPath,
+};