Une seule dépendance : construire un serveur de production avec juste le package ws

Ouvrez le package.json du serveur Tactic Remote. Sous dependencies, vous trouverez exactement une entrée :

{
  "dependencies": {
    "ws": "^8.18.0"
  }
}

C'est tout. Un package. La bibliothèque WebSocket ws. Tout le reste — le serveur HTTP, l'authentification, la limitation de débit, la gestion de terminal, la navigation de fichiers, la validation des entrées, l'exécution de processus — est construit sur les modules natifs de Node.js.

Ce n'est pas du minimalisme accidentel. C'est une décision d'ingénierie délibérée avec des conséquences concrètes pour la fiabilité, la sécurité et les utilisateurs de notre logiciel.

Pourquoi c'est important

Le serveur tourne sur votre Mac, gérant vos sessions Claude Code. Il a accès à votre terminal, votre système de fichiers et vos processus en cours. Chaque dépendance que vous ajoutez à un tel système est :

1. Une surface d'attaque. Chaque package npm est du code qui s'exécute avec vos permissions, écrit par quelqu'un que vous ne connaissez pas, avec des dépendances transitives que vous n'avez pas auditées.
2. Un fardeau de maintenance. Les dépendances ont besoin de mises à jour. Les mises à jour peuvent introduire des changements cassants ou des vulnérabilités. Plus vous en avez, plus souvent vous faites npm audit fix au lieu de construire des fonctionnalités.
3. Un risque de fiabilité. Quand une dépendance casse (leftpad, colors, node-ipc), votre serveur casse. Les workflows de développement de vos utilisateurs s'arrêtent.

Pour un serveur qui se situe entre un humain et une IA écrivant du code sur sa machine, le coût d'une compromission de dépendance est sévère. Nous avons décidé que le bon nombre de dépendances externes était aussi proche de zéro que possible.

Ce que nous avons construit sans dépendances

Serveur HTTP

Node.js fournit http.createServer(). Ce n'est pas Express, mais nous servons exactement deux endpoints HTTP :

// POST /hook — reçoit les événements du cycle de vie Claude Code
// GET /status — health check avec info du dernier événement

Deux routes. Pas de chaînes de middleware, pas de parseurs de body, pas de bibliothèques de routage. Le gestionnaire de requêtes est une seule fonction qui vérifie le chemin URL avec ===, lit le corps de la requête avec req.on('data'), et appelle le gestionnaire approprié.

Est-ce « webscale » ? Non. Est-ce que ça doit l'être ? Non plus. Ce serveur gère une connexion d'un iPhone. Une bibliothèque de routage serait du théâtre d'ingénierie.

Authentification

Le système d'auth supporte deux formats d'en-tête pour la vérification de clé API :

// Endpoints HTTP
const apiKey = req.headers['x-api-key'] || req.headers['authorization']?.replace('Bearer ', '')
 
// Connexions WebSocket
const apiKey =
  req.headers['authorization']?.replace('Bearer ', '') || req.headers['sec-websocket-protocol']

Le repli sur Sec-WebSocket-Protocol existe parce que URLSessionWebSocketTask sur iOS ne peut pas définir d'en-têtes arbitraires sur la requête d'upgrade. C'est une limitation documentée d'iOS — vous pouvez définir l'en-tête de protocole, mais pas d'en-têtes personnalisés. Plutôt que d'importer une bibliothèque WebSocket qui contourne cela, nous utilisons l'en-tête de protocole comme canal d'authentification.

L'authentification est vérifiée une fois à la connexion. En cas d'échec, le WebSocket se ferme avec le code 1008 (Policy Violation). Pas de tokens de session, pas de flux de refresh, pas de bibliothèques JWT. Une clé API statique, comparée avec ===.

Limitation de débit

Une fenêtre glissante en mémoire, 40 lignes de code :

class RateLimiter {
  constructor(maxAttempts = 30, windowMs = 60000) {
    this.attempts = new Map() // IP -> { count, resetTime }
    this.maxAttempts = maxAttempts
    this.windowMs = windowMs
 
    // Nettoyage des entrées périmées toutes les 5 minutes
    setInterval(() => this.cleanup(), 300000)
  }
 
  isRateLimited(ip) {
    const now = Date.now()
    const record = this.attempts.get(ip)
 
    if (!record || now > record.resetTime) {
      this.attempts.set(ip, { count: 1, resetTime: now + this.windowMs })
      return false
    }
 
    record.count++
    return record.count > this.maxAttempts
  }
}

30 tentatives d'authentification échouées par minute par IP. Au-delà, le serveur retourne 429 Too Many Requests avec un champ retryAfter. Quand la fenêtre expire, le compteur se réinitialise.

Un rate limiter basé sur Redis serait plus sophistiqué. Il ajouterait aussi une dépendance Redis. Pour un serveur gérant un seul client, un Map en mémoire avec nettoyage périodique est approprié.

Validation des entrées

Chaque saisie utilisateur est validée avant de toucher le système. Voici la surface de validation complète :

Pas de bibliothèque de validation. Des expressions régulières et de la comparaison de chaînes, en ligne et lisibles.

Exécution de processus

C'est la pièce critique en termes de sécurité. Le serveur exécute des commandes tmux en votre nom. Si cette couche a une vulnérabilité, un attaquant peut exécuter des commandes arbitraires sur votre machine.

Notre réponse : child_process.spawn() avec shell: false, encapsulé dans une seule fonction par laquelle passe chaque commande externe :

function execSafe(cmd, args = [], opts = {}) {
  return new Promise((resolve, reject) => {
    const child = spawn(cmd, args, {
      shell: false, // Pas d'interpolation shell. Point final.
      ...opts,
    })
 
    let stdout = ''
    let stderr = ''
 
    child.stdout?.on('data', (data) => {
      stdout += data
    })
    child.stderr?.on('data', (data) => {
      stderr += data
    })
 
    child.on('close', (code) => {
      if (code === 0) resolve({ stdout, stderr, code })
      else reject(new Error(`Exit code ${code}: ${stderr}`))
    })
  })
}

shell: false signifie que les arguments sont passés directement au processus, pas via /bin/sh. Il n'y a pas d'interpolation de chaîne, pas d'expansion de template literal, pas d'opportunité d'injection shell. Si vous passez ["send-keys", "-t", sessionName, "-l", content] comme tableau d'arguments, c'est exactement ce que tmux reçoit dans son argv. Les points-virgules, pipes, backticks, $() — aucun d'entre eux n'a de signification spéciale.

Chaque opération tmux est un wrapper fin autour de cette fonction :

async function tmuxSendKeys(sessionName, keys) {
  return execSafe('tmux', ['send-keys', '-t', sessionName, ...keys])
}
 
async function tmuxCapture(sessionName, lines = 500) {
  const result = await execSafe('tmux', [
    'capture-pane',
    '-t',
    sessionName,
    '-p',
    '-S',
    `-${lines}`,
  ])
  return result.stdout
}
 
async function tmuxNewSession(name, dir) {
  await execSafe('tmux', ['new-session', '-d', '-s', name, '-c', dir])
  await execSafe('tmux', ['set-option', '-t', name, 'history-limit', '50000'])
}

Pas de bibliothèque wrapper tmux. Pas d'ORM pour les sessions terminal. Juste spawn avec des tableaux d'arguments explicites.

Protection contre la traversée de chemin

La navigation de fichiers restreint l'accès à l'arborescence du répertoire personnel. Les répertoires sensibles sont toujours bloqués :

const SENSITIVE_DIRS = [
  '.ssh',
  '.gnupg',
  '.aws',
  '.kube',
  '.config/gcloud',
  'Library/Keychains',
  'Library/Cookies',
  'Library/Application Support/1Password',
]
 
function containsSensitiveDir(targetPath) {
  const segments = targetPath.split(path.sep)
  return SENSITIVE_DIRS.some((sensitive) => {
    const sensitiveSegments = sensitive.split(path.sep)
    return segments.some((_, i) => sensitiveSegments.every((seg, j) => segments[i + j] === seg))
  })
}

Correspondance segment par segment. Pas includes() sur la chaîne du chemin, ce qui donnerait un faux positif sur un répertoire nommé my-.ssh-backup. La vérification cherche des segments de chemin consécutifs qui correspondent exactement au pattern du répertoire sensible.

Tous les chemins sont résolus en chemins absolus via path.resolve() avant vérification. Cela neutralise la traversée avec .., les attaques par lien symbolique et les astuces de chemins relatifs.

Le protocole WebSocket

Le package ws nous donne un serveur WebSocket. Par-dessus, nous avons construit un système dual-protocole qui gère simultanément notre format de message plat original et un format structuré plus récent.

Pourquoi deux protocoles

Nous avons d'abord livré le protocole plat :

{ "type": "send_to_claude", "content": "fix the bug", "session": "webapp" }

Ça fonctionne, mais il n'y a pas de corrélation de requête. Si le client envoie deux requêtes coup sur coup, les réponses arrivent comme des messages séparés et le client ne peut pas dire quelle réponse correspond à quelle requête.

Le nouveau protocole ajoute des ID de requête :

{"type": "req", "id": "abc-123", "method": "send_to_claude", "params": {"content": "fix the bug"}}
{"type": "res", "id": "abc-123", "ok": true, "payload": {"status": "sent"}}

Nous ne pouvions pas casser les clients existants en supprimant le format plat. Donc le serveur gère les deux :

function handleMessage(ws, data) {
    const msg = JSON.parse(data);
 
    if (msg.type === 'req') {
        // Nouveau protocole : extraire méthode et params, appeler le handler,
        // répondre avec l'id correspondant
        const result = await handlers[msg.method](msg.params);
        sendToClient(ws, { type: 'res', id: msg.id, ok: true, payload: result });
    } else {
        // Protocole legacy : type EST la méthode
        const result = await handlers[msg.type](msg);
        sendToClient(ws, { type: 'status', ...result });
    }
}

Le WebSocketClient de l'app iOS fait la même chose côté client — essaie de décoder les messages entrants comme le nouveau protocole Frame d'abord, se replie sur le ServerMessage legacy en cas d'échec.

Heartbeat

Les connexions WebSocket mobiles sont fragiles. Le téléphone bascule entre WiFi et cellulaire, se met en veille, entre dans des zones mortes. Nous devons détecter rapidement les connexions mortes sans tuer les connexions simplement interrompues temporairement.

setInterval(() => {
  this.wss.clients.forEach((ws) => {
    if (ws.isAlive === false) {
      ws.missedHeartbeats = (ws.missedHeartbeats || 0) + 1
      if (ws.missedHeartbeats >= 2) {
        return ws.terminate()
      }
    } else {
      ws.missedHeartbeats = 0
    }
    ws.isAlive = false
    ws.ping()
  })
}, 45000)

Intervalle de 45 secondes, tolérance à 2 échecs. Un client peut être non réactif pendant 90 secondes avant d'être terminé. C'est calibré pour le mobile — un heartbeat WebSocket typique est de 15-30 secondes, mais les clients mobiles traversent fréquemment des transitions réseau de 30-60 secondes en changeant d'antenne ou en se réassociant au WiFi.

Nous envoyons à la fois un ping au niveau WebSocket (que la bibliothèque ws gère automatiquement) et un message {"type": "ping"} au niveau application. Le ping applicatif est pour les clients qui ne peuvent pas accéder directement aux trames WebSocket de bas niveau (une autre contrainte de URLSessionWebSocketTask sur iOS).

Ce que nous n'avons pas

Soyons honnêtes sur ce que cette architecture n'a pas :

Pas de clustering. Le serveur est mono-processus, mono-machine. Il ne peut pas scaler horizontalement. Il n'en a pas besoin — il sert un utilisateur sur un Mac.

Pas de persistance. Si le serveur redémarre, l'état du rate limiter et le registre des clients sont perdus. Les sessions tmux survivent (ce sont des processus indépendants), mais l'état en mémoire du serveur non. Pour notre cas d'usage, c'est acceptable — le client se reconnecte et rétablit l'état en quelques secondes.

Pas d'orchestration d'arrêt gracieux. Quand le serveur s'arrête, les connexions WebSocket sont terminées, pas drainées. Encore une fois, acceptable pour un serveur mono-utilisateur — le client gère la reconnexion.

Pas de logging de requêtes ni d'APM. Nous logons vers stdout. Si vous avez besoin de plus, redirigez vers un fichier. Il n'y a pas de bibliothèque de logging structuré, pas d'intégration OpenTelemetry, pas d'agrégation de logs.

Ce sont toutes des fonctionnalités qui ont du sens pour les services cloud multi-tenants. Elles n'en ont pas pour un serveur qui tourne sur votre bureau et sert votre téléphone.

La réalité de la maintenance

Depuis le lancement, notre maintenance de dépendances a été :

• Mettre à jour ws quand il y a un correctif de sécurité
• C'est tout

Pas d'alertes npm audit de dépendances transitives. Pas de PRs Dependabot pour des bibliothèques que nous n'utilisons pas directement. Pas de changements cassants de bumps de version majeure de frameworks middleware.

Quand la bibliothèque ws a une vulnérabilité (c'est arrivé deux fois depuis le début), nous mettons à jour un package. Le changement est petit, le risque est contenu, et nous pouvons auditer le diff en cinq minutes.

Comparez avec une stack typique Express + passport + helmet + compression + cors + body-parser. Chacun de ceux-ci tire son propre arbre de dépendances. Un seul npm audit peut signaler des dizaines de vulnérabilités transitives, la plupart théoriques mais toutes nécessitant une investigation.

Quand cette approche ne fonctionne pas

Pour être clair : ce n'est pas une recommandation générale. Les serveurs à une seule dépendance fonctionnent quand :

• Vous servez un seul utilisateur ou un petit ensemble connu de clients
• Votre surface HTTP est minuscule (1-5 routes)
• Vous n'avez pas besoin d'accès base de données, de templating ou de routage complexe
• La sécurité est mieux servie par la simplicité que par l'empilement de bibliothèques
• Votre équipe est à l'aise avec les API natives de Node.js

Si vous construisez un SaaS avec des comptes utilisateurs, OAuth, des modèles de base de données et une API REST, utilisez un framework. Express ou Fastify avec un ORM approprié vous fera gagner des mois de travail. L'approche « une dépendance » est pour les systèmes où le coût de la dépendance dépasse le coût de l'implémentation.

Pour le serveur de Tactic Remote — un relais WebSocket mono-utilisateur, mono-usage entre tmux et un iPhone — une dépendance est le bon nombre.

Pour voir comment ce serveur s'intègre dans l'architecture globale, consultez Exécuter Claude Code à distance depuis votre téléphone. Pour la référence complète du protocole WebSocket, consultez le guide de démarrage.