@piecemaker-legal/piecemaker 1.0.6

package/server/piecemaker/anonymizer/providers.cjs

@@ -0,0 +1,241 @@
+/**
+ * Branchement des quatre clients IA de CloudCLI sur le proxy PII.
+ *
+ * Chaque client a son propre levier, et un seul est universel : la variable
+ * d'environnement du serveur, dont héritent les quatre chemins de lancement.
+ * Elle ne suffit pourtant que là où le CLI honore une base d'URL, d'où un
+ * second levier — le fichier de configuration utilisateur — pour Codex et
+ * opencode, et un troisième pour Cursor, qui n'en honore aucun.
+ *
+ *  | client   | levier                                             |
+ *  |----------|----------------------------------------------------|
+ *  | claude   | `ANTHROPIC_BASE_URL` + `~/.claude/settings.json`   |
+ *  | codex    | `~/.codex/config.toml` (bloc géré)                  |
+ *  | opencode | `provider.*.options.baseURL` de sa configuration    |
+ *  | cursor   | aucun — voir plus bas                               |
+ *
+ * **Cursor.** `cursor-agent` parle le protocole d'authentification de Cursor et
+ * ignore toute base d'URL : il n'est pas interceptable. Le laisser tourner
+ * enverrait des noms de parties en clair. À défaut de pouvoir le filtrer, on
+ * l'empêche de partir : un exécutable `cursor-agent` posé en tête de `PATH`
+ * refuse de s'exécuter tant qu'un mapping existe, et relaie le vrai binaire
+ * sinon. C'est le seul fournisseur pour lequel la garantie se paie d'un refus,
+ * et cela reste préférable à une fuite silencieuse.
+ *
+ * La configuration Claude et Codex est écrite par `./client-config.cjs`,
+ * propre à ce dépôt : écriture atomique, détection de conflit et
+ * réversibilité, sous l'identifiant de bloc `piecemaker_proxy`.
+ */
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const {
+  configureClaudeCodeProxy,
+  bypassClaudeCodeProxy,
+  configureCodexProxy,
+  bypassCodexProxy,
+} = require('./client-config.cjs');
+
+/** Une base que PieceMaker a écrite — donc que PieceMaker peut réécrire ou retirer. */
+function isOwnLoopbackUrl(value, suffix) {
+  try {
+    const url = new URL(String(value || ''));
+    return ['127.0.0.1', 'localhost'].includes(url.hostname)
+      && url.pathname.replace(/\/$/, '') === suffix;
+  } catch {
+    return false;
+  }
+}
+
+function opencodeConfigFile(userHome) {
+  if (process.env.OPENCODE_CONFIG) return process.env.OPENCODE_CONFIG;
+  const base = process.env.XDG_CONFIG_HOME || path.join(userHome, '.config');
+  return path.join(base, 'opencode', 'opencode.json');
+}
+
+function writeJsonAtomic(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.piecemaker-${process.pid}`;
+  fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  fs.renameSync(temporary, file);
+}
+
+/**
+ * opencode lit `provider.<id>.options.baseURL`. On câble les deux familles que
+ * le proxy sait router ; les autres fournisseurs éventuellement configurés
+ * restent intacts, et donc hors couverture — le statut le dit.
+ */
+const OPENCODE_ROUTES = [
+  { id: 'anthropic', suffix: '/anthropic' },
+  { id: 'openai', suffix: '/openai' },
+];
+
+function configureOpencode({ origin, userHome }) {
+  const file = opencodeConfigFile(userHome);
+  let config = {};
+  try {
+    if (fs.existsSync(file)) {
+      const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('objet JSON attendu');
+      config = parsed;
+    }
+  } catch {
+    return { configured: false, changed: false, conflict: true, file, reason: 'config-invalid' };
+  }
+
+  if (config.provider !== undefined
+    && (!config.provider || typeof config.provider !== 'object' || Array.isArray(config.provider))) {
+    return { configured: false, changed: false, conflict: true, file, reason: 'provider-invalid' };
+  }
+  if (!config.provider) config.provider = {};
+
+  let changed = false;
+  for (const { id, suffix } of OPENCODE_ROUTES) {
+    const target = `${origin}${suffix}`;
+    const entry = config.provider[id];
+    if (entry !== undefined && (!entry || typeof entry !== 'object' || Array.isArray(entry))) {
+      return { configured: false, changed: false, conflict: true, file, reason: `provider-${id}-invalid` };
+    }
+    const options = entry?.options;
+    if (options !== undefined && (!options || typeof options !== 'object' || Array.isArray(options))) {
+      return { configured: false, changed: false, conflict: true, file, reason: `options-${id}-invalid` };
+    }
+    const existing = options?.baseURL;
+    // Une base tierce délibérément posée par l'utilisateur n'est pas écrasée :
+    // on signale le conflit plutôt que de casser sa configuration en silence.
+    if (existing && existing !== target && !isOwnLoopbackUrl(existing, suffix)) {
+      return { configured: false, changed: false, conflict: true, file, reason: `base-url-conflict:${id}` };
+    }
+    if (existing === target) continue;
+    config.provider[id] = { ...entry, options: { ...options, baseURL: target } };
+    changed = true;
+  }
+
+  if (changed) writeJsonAtomic(file, config);
+  return { configured: true, changed, conflict: false, file };
+}
+
+function bypassOpencode({ userHome }) {
+  const file = opencodeConfigFile(userHome);
+  if (!fs.existsSync(file)) return { bypassed: true, changed: false, conflict: false, file };
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error('objet JSON attendu');
+  } catch {
+    return { bypassed: false, changed: false, conflict: true, file, reason: 'config-invalid' };
+  }
+
+  let changed = false;
+  for (const { id, suffix } of OPENCODE_ROUTES) {
+    const options = config.provider?.[id]?.options;
+    if (!options || typeof options !== 'object' || Array.isArray(options)) continue;
+    if (!isOwnLoopbackUrl(options.baseURL, suffix)) continue;
+    delete options.baseURL;
+    if (Object.keys(options).length === 0) delete config.provider[id].options;
+    if (Object.keys(config.provider[id]).length === 0) delete config.provider[id];
+    changed = true;
+  }
+  if (changed && config.provider && Object.keys(config.provider).length === 0) delete config.provider;
+  if (changed) writeJsonAtomic(file, config);
+  return { bypassed: true, changed, conflict: false, file };
+}
+
+/** Première ligne du garde-fou Cursor : ce que le shim écrit avant de renoncer. */
+const CURSOR_REFUSAL = 'PieceMaker : cursor-agent ne peut pas être filtré par le proxy d’anonymisation '
+  + '(son protocole n’accepte aucune base d’URL). Tant qu’un mapping existe, il est bloqué pour éviter '
+  + 'que des noms de parties quittent la machine en clair. Utilisez Claude, Codex ou opencode.';
+
+/**
+ * Écrit le shim `cursor-agent` dans un répertoire que le service place en tête
+ * de `PATH`. Le shim ne lit jamais le contenu du mapping — sa seule existence
+ * décide —, et se retire du `PATH` avant de relayer le vrai binaire pour ne pas
+ * se rappeler lui-même.
+ */
+function installCursorGuard({ binDir, mappingFile }) {
+  fs.mkdirSync(binDir, { recursive: true });
+  const file = path.join(binDir, 'cursor-agent');
+  const script = `#!/bin/sh
+# Généré par PieceMaker — ne pas modifier. Voir server/piecemaker/anonymizer/providers.cjs
+if [ -s ${JSON.stringify(mappingFile)} ]; then
+  printf '%s\\n' ${JSON.stringify(CURSOR_REFUSAL)} >&2
+  exit 78
+fi
+PATH=$(printf '%s' "$PATH" | sed -e "s|^${binDir.replace(/[|\\]/g, '\\$&')}:||")
+export PATH
+exec cursor-agent "$@"
+`;
+  fs.writeFileSync(file, script, { encoding: 'utf8', mode: 0o755 });
+  return { file, binDir };
+}
+
+/**
+ * Câble tous les fournisseurs sur `origin` et rend un rapport par client.
+ * Aucun échec n'est fatal : un client mal configuré est signalé « non couvert »
+ * dans le statut, ce qui est l'information utile, plutôt que d'empêcher le
+ * serveur de démarrer.
+ */
+async function configureProviders({ origin, userHome = os.homedir(), binDir, mappingFile }) {
+  const report = {};
+
+  const attempt = (name, run) => {
+    try {
+      report[name] = run();
+    } catch (error) {
+      report[name] = { configured: false, changed: false, conflict: true, reason: error.message };
+    }
+  };
+
+  attempt('claude', () => configureClaudeCodeProxy({ baseUrl: `${origin}/anthropic`, userHome }));
+  attempt('codex', () => configureCodexProxy({
+    baseUrl: `${origin}/chatgpt`,
+    codexHome: process.env.CODEX_HOME || path.join(userHome, '.codex'),
+  }));
+  attempt('opencode', () => configureOpencode({ origin, userHome }));
+  attempt('cursor', () => ({
+    configured: false,
+    changed: false,
+    conflict: false,
+    blocked: true,
+    reason: 'not-interceptable',
+    ...installCursorGuard({ binDir, mappingFile }),
+  }));
+
+  return report;
+}
+
+/** Défait tout ce que `configureProviders` a posé : l'arrêt du serveur ne doit pas laisser de base morte. */
+async function bypassProviders({ userHome = os.homedir(), binDir }) {
+  const report = {};
+  const attempt = (name, run) => {
+    try {
+      report[name] = run();
+    } catch (error) {
+      report[name] = { bypassed: false, conflict: true, reason: error.message };
+    }
+  };
+
+  attempt('claude', () => bypassClaudeCodeProxy({ userHome }));
+  attempt('codex', () => bypassCodexProxy({ codexHome: process.env.CODEX_HOME || path.join(userHome, '.codex') }));
+  attempt('opencode', () => bypassOpencode({ userHome }));
+  attempt('cursor', () => {
+    const file = path.join(binDir, 'cursor-agent');
+    if (fs.existsSync(file)) fs.rmSync(file);
+    return { bypassed: true, file };
+  });
+  return report;
+}
+
+module.exports = {
+  CURSOR_REFUSAL,
+  OPENCODE_ROUTES,
+  bypassOpencode,
+  bypassProviders,
+  configureOpencode,
+  configureProviders,
+  installCursorGuard,
+  isOwnLoopbackUrl,
+  opencodeConfigFile,
+};

package/server/piecemaker/anonymizer/proxy.cjs

@@ -0,0 +1,365 @@
+/**
+ * Proxy PII local — le seul point de passage entre les clients IA lancés par
+ * CloudCLI (chat comme terminal) et les API des fournisseurs.
+ *
+ * Sans Python, sans venv, sans service de session à installer : il vit dans
+ * le cycle de vie du serveur CloudCLI plutôt qu'à côté.
+ *
+ * Sens sortant  : nom réel → code. Aucun nom de partie ne quitte la machine.
+ * Sens entrant  : code → nom réel. Claude Code retrouve un texte lisible, ses
+ *                 outils continuent d'ouvrir les fichiers sous leur vrai nom, et
+ *                 l'interface n'a plus qu'à surligner ce qui a été protégé.
+ *
+ * Sans mapping, le proxy est un relais transparent : le brancher ne peut pas
+ * casser une installation qui n'a encore anonymisé aucun dossier.
+ *
+ * Une route par fournisseur, distinguée par le préfixe d'URL. Un chemin qui ne
+ * correspond à aucune route est refusé : router par défaut reviendrait à
+ * laisser passer non filtré ce que l'on n'a pas su reconnaître.
+ */
+const http = require('node:http');
+const https = require('node:https');
+
+const { anonymize, deanonymize } = require('./dictionary.cjs');
+const { createSseRewriter, rewriteJsonBody } = require('./rewrite.cjs');
+const { createCollecteurTexte } = require('../harness/flux-sse.cjs');
+
+const DEFAULT_UPSTREAM = 'https://api.anthropic.com';
+
+/**
+ * Routes servies par défaut. `/chatgpt` vise le point d'entrée Codex de
+ * ChatGPT, où le CLI parle le protocole Responses avec l'authentification
+ * ChatGPT.
+ */
+const DEFAULT_ROUTES = [
+  { provider: 'claude', prefix: '/anthropic', upstream: 'https://api.anthropic.com' },
+  { provider: 'codex', prefix: '/chatgpt', upstream: 'https://chatgpt.com/backend-api/codex' },
+  { provider: 'opencode', prefix: '/openai', upstream: 'https://api.openai.com' },
+];
+
+/** Port fixe : une base écrite dans un fichier de configuration doit survivre à un redémarrage. */
+const DEFAULT_PORT = 4111;
+
+/**
+ * En-têtes que le proxy possède et ne relaie donc jamais tels quels. Le corps
+ * change de taille à la réécriture (`content-length`), et `accept-encoding` est
+ * retiré pour recevoir du texte clair : compresser en amont rendrait la
+ * dé-anonymisation impossible sans décompresser tout le flux.
+ */
+const DROPPED_REQUEST_HEADERS = new Set(['host', 'content-length', 'accept-encoding', 'connection']);
+const DROPPED_RESPONSE_HEADERS = new Set(['content-length', 'content-encoding', 'connection', 'transfer-encoding']);
+
+function pickHeaders(source, dropped) {
+  const output = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (dropped.has(key.toLowerCase())) continue;
+    output[key] = value;
+  }
+  return output;
+}
+
+function readBody(stream, limitBytes) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    stream.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > limitBytes) {
+        reject(new Error(`Corps de requête trop volumineux (> ${limitBytes} octets).`));
+        stream.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    stream.on('end', () => resolve(Buffer.concat(chunks)));
+    stream.on('error', reject);
+  });
+}
+
+function isJsonLike(contentType) {
+  return /\bjson\b/i.test(String(contentType || ''));
+}
+
+function isEventStream(contentType) {
+  return /text\/event-stream/i.test(String(contentType || ''));
+}
+
+/**
+ * Texte assistant d'un corps JSON complet (non streamé), pour le harnais de
+ * citations : formes Anthropic Messages (`content[]`, blocs `{type:'text'}`)
+ * et Responses d'OpenAI (`output[].content[]`, blocs `{type:'output_text'}`).
+ * Ne jette jamais : un corps illisible ou d'une autre forme renvoie `''`.
+ */
+function extractAssistantTextFromJson(raw) {
+  try {
+    const parsed = JSON.parse(typeof raw === 'string' ? raw : raw.toString('utf8'));
+    if (!parsed || typeof parsed !== 'object') return '';
+    if (Array.isArray(parsed.content)) {
+      return parsed.content
+        .filter((block) => block?.type === 'text' && typeof block.text === 'string')
+        .map((block) => block.text)
+        .join('');
+    }
+    if (Array.isArray(parsed.output)) {
+      return parsed.output
+        .flatMap((item) => (Array.isArray(item?.content) ? item.content : []))
+        .filter((block) => block?.type === 'output_text' && typeof block.text === 'string')
+        .map((block) => block.text)
+        .join('');
+    }
+    return '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * @param {object} options
+ * @param {{ get: () => object }} options.dictionary Chargeur de mapping à chaud.
+ * @param {Array<{provider: string, prefix: string, upstream: string}>} [options.routes]
+ *   Table de routage ; le préfixe le plus long l'emporte.
+ * @param {number} [options.port] Port préféré ; 0 = port éphémère.
+ * @param {object|null} [options.harness] Harnais de citations vérifiées
+ *   (`../harness/index.cjs`), absent par défaut : sans lui, le proxy se
+ *   comporte exactement comme s'il n'existait pas.
+ */
+function createAnonymizerProxy({
+  dictionary,
+  routes = DEFAULT_ROUTES,
+  port = DEFAULT_PORT,
+  host = '127.0.0.1',
+  maxBodyBytes = 64 * 1024 * 1024,
+  onError = () => {},
+  harness = null,
+} = {}) {
+  // Préfixe le plus long d'abord : `/anthropic/v1` doit gagner sur `/anthropic`
+  // si les deux sont déclarés un jour.
+  const table = [...routes]
+    .map((route) => ({ ...route, target: new URL(route.upstream) }))
+    .sort((left, right) => right.prefix.length - left.prefix.length);
+  const stats = { requests: 0, anonymized: 0, deanonymized: 0, failures: 0, lastError: null };
+
+  // Observation du harnais de citations, en espace clair des deux côtés
+  // (corps brut du client à l'aller, texte livré au client au retour) — voir
+  // `../harness/index.cjs`. Ne doit jamais retarder ni faire échouer une
+  // requête ou une réponse déjà en cours, même si le harnais fourni est
+  // défaillant (double garde : `index.cjs` ne jette déjà jamais, mais le
+  // proxy ne doit dépendre de cette garantie).
+  function observerRequete(rawBody, contentType, session) {
+    if (!harness) return;
+    try {
+      harness.observerRequete(rawBody, contentType, { session });
+    } catch {
+      // jamais bloquant pour la requête en cours
+    }
+  }
+
+  function observerReponse(texteAssistant, session) {
+    if (!harness) return;
+    try {
+      Promise.resolve(harness.observerReponse(texteAssistant, { session })).catch(() => {});
+    } catch {
+      // jamais bloquant pour une réponse déjà envoyée au client
+    }
+  }
+
+  function matchRoute(url) {
+    return table.find((route) => url === route.prefix || url.startsWith(`${route.prefix}/`) || url.startsWith(`${route.prefix}?`));
+  }
+
+  const server = http.createServer((clientRequest, clientResponse) => {
+    stats.requests += 1;
+    const current = dictionary.get();
+
+    const route = matchRoute(clientRequest.url || '');
+    if (!route) {
+      stats.failures += 1;
+      stats.lastError = `Chemin non routé : ${clientRequest.url}`;
+      clientResponse.writeHead(404, { 'content-type': 'application/json' });
+      clientResponse.end(JSON.stringify({
+        error: {
+          type: 'piecemaker_proxy',
+          message: `Aucune route d'anonymisation pour ${clientRequest.url}. Requête refusée plutôt que relayée sans filtrage.`,
+        },
+      }));
+      return;
+    }
+    const { target } = route;
+    const transport = target.protocol === 'http:' ? http : https;
+    const forwardedPath = `${target.pathname.replace(/\/$/, '')}${clientRequest.url.slice(route.prefix.length) || '/'}`;
+
+    void (async () => {
+      let body = Buffer.alloc(0);
+      try {
+        body = await readBody(clientRequest, maxBodyBytes);
+      } catch (error) {
+        stats.failures += 1;
+        stats.lastError = error.message;
+        clientResponse.writeHead(413, { 'content-type': 'application/json' });
+        clientResponse.end(JSON.stringify({ error: { type: 'piecemaker_proxy', message: error.message } }));
+        return;
+      }
+
+      // Corps brut, AVANT anonymisation : le harnais doit voir le même texte
+      // que le client a envoyé, pas les codes qui partent vers le fournisseur.
+      observerRequete(body, clientRequest.headers['content-type'], route.provider);
+
+      let outgoing = body;
+      if (body.length && !current.empty && isJsonLike(clientRequest.headers['content-type'])) {
+        const rewritten = rewriteJsonBody(body, (text) => anonymize(text, current));
+        outgoing = Buffer.from(rewritten, 'utf8');
+        if (!outgoing.equals(body)) stats.anonymized += 1;
+      }
+
+      const headers = pickHeaders(clientRequest.headers, DROPPED_REQUEST_HEADERS);
+      headers.host = target.host;
+      headers['accept-encoding'] = 'identity';
+      if (outgoing.length) headers['content-length'] = String(outgoing.length);
+
+      const upstreamRequest = transport.request(
+        {
+          protocol: target.protocol,
+          hostname: target.hostname,
+          port: target.port || (target.protocol === 'http:' ? 80 : 443),
+          method: clientRequest.method,
+          path: forwardedPath,
+          headers,
+        },
+        (upstreamResponse) => {
+          const responseHeaders = pickHeaders(upstreamResponse.headers, DROPPED_RESPONSE_HEADERS);
+          clientResponse.writeHead(upstreamResponse.statusCode || 502, responseHeaders);
+
+          if (current.empty) {
+            // Rien à dé-anonymiser, mais le harnais observe quand même ce qui
+            // est livré au client — inchangé, aucune réécriture ici.
+            if (isEventStream(upstreamResponse.headers['content-type'])) {
+              const collecteur = createCollecteurTexte();
+              upstreamResponse.setEncoding('utf8');
+              upstreamResponse.on('data', (chunk) => {
+                collecteur.push(chunk);
+                clientResponse.write(chunk);
+              });
+              upstreamResponse.on('end', () => {
+                clientResponse.end();
+                observerReponse(collecteur.texte(), route.provider);
+              });
+              upstreamResponse.on('error', () => clientResponse.end());
+              return;
+            }
+            if (isJsonLike(upstreamResponse.headers['content-type'])) {
+              const chunks = [];
+              upstreamResponse.on('data', (chunk) => chunks.push(chunk));
+              upstreamResponse.on('end', () => {
+                const raw = Buffer.concat(chunks);
+                clientResponse.end(raw);
+                observerReponse(extractAssistantTextFromJson(raw), route.provider);
+              });
+              upstreamResponse.on('error', () => clientResponse.end());
+              return;
+            }
+            upstreamResponse.pipe(clientResponse);
+            return;
+          }
+
+          const revert = (text) => deanonymize(text, current);
+
+          if (isEventStream(upstreamResponse.headers['content-type'])) {
+            const rewriter = createSseRewriter(revert);
+            const collecteur = createCollecteurTexte();
+            upstreamResponse.setEncoding('utf8');
+            upstreamResponse.on('data', (chunk) => {
+              const out = rewriter.push(chunk);
+              if (out) {
+                clientResponse.write(out);
+                collecteur.push(out);
+              }
+            });
+            upstreamResponse.on('end', () => {
+              const tail = rewriter.end();
+              if (tail) {
+                clientResponse.write(tail);
+                collecteur.push(tail);
+              }
+              stats.deanonymized += 1;
+              clientResponse.end();
+              observerReponse(collecteur.texte(), route.provider);
+            });
+            upstreamResponse.on('error', () => clientResponse.end());
+            return;
+          }
+
+          if (isJsonLike(upstreamResponse.headers['content-type'])) {
+            const chunks = [];
+            upstreamResponse.on('data', (chunk) => chunks.push(chunk));
+            upstreamResponse.on('end', () => {
+              const raw = Buffer.concat(chunks);
+              const rewritten = rewriteJsonBody(raw, revert);
+              stats.deanonymized += 1;
+              clientResponse.end(rewritten);
+              observerReponse(extractAssistantTextFromJson(rewritten), route.provider);
+            });
+            upstreamResponse.on('error', () => clientResponse.end());
+            return;
+          }
+
+          upstreamResponse.pipe(clientResponse);
+        },
+      );
+
+      upstreamRequest.on('error', (error) => {
+        stats.failures += 1;
+        stats.lastError = error.message;
+        onError(error);
+        if (clientResponse.headersSent) {
+          clientResponse.end();
+          return;
+        }
+        clientResponse.writeHead(502, { 'content-type': 'application/json' });
+        clientResponse.end(JSON.stringify({
+          error: { type: 'piecemaker_proxy', message: `Relais indisponible : ${error.message}` },
+        }));
+      });
+
+      if (outgoing.length) upstreamRequest.write(outgoing);
+      upstreamRequest.end();
+    })();
+  });
+
+  function listenOn(candidate) {
+    return new Promise((resolve, reject) => {
+      const onError = (error) => reject(error);
+      server.once('error', onError);
+      server.listen(candidate, host, () => {
+        server.removeListener('error', onError);
+        const address = server.address();
+        resolve({ port: address.port, origin: `http://${host}:${address.port}` });
+      });
+    });
+  }
+
+  return {
+    stats,
+    get listening() { return server.listening; },
+    routes: table.map(({ provider, prefix, target }) => ({ provider, prefix, upstream: target.origin })),
+    /**
+     * Écoute le port demandé, et lui seul. La base écrite dans les
+     * configurations des clients leur survit sur disque : un port qui dérive
+     * la rend définitivement fausse pour la session suivante. Un port déjà
+     * pris signale une instance encore vivante, pas une invitation à bouger.
+     */
+    async listen() {
+      try {
+        return await listenOn(port);
+      } catch (error) {
+        if (error.code !== 'EADDRINUSE') throw error;
+        throw new Error(`Port ${port} déjà occupé : une instance du proxy PII écoute encore. `
+          + `Arrêtez-la (lsof -nP -iTCP:${port} -sTCP:LISTEN) avant de redémarrer.`);
+      }
+    },
+    close() {
+      return new Promise((resolve) => server.close(() => resolve()));
+    },
+  };
+}
+
+module.exports = { DEFAULT_UPSTREAM, createAnonymizerProxy };