localhostly 0.0.0-stage → 1.1.0

package/agente/tunel.js

@@ -0,0 +1,356 @@
+// O agente: uma conexão de saída ao servidor e cada requisição reproduzida na porta local.
+import { EventEmitter } from 'node:events';
+import http from 'node:http';
+import { performance } from 'node:perf_hooks';
+import WebSocket from 'ws';
+import { Canal } from '../lib/canal.js';
+import { filtrar, paraObjeto, sem, valor } from '../lib/cabecalhos.js';
+import { entregar, Remetente, segurarWs } from '../lib/fluxo.js';
+import { codigoEnviavel, TIPO } from '../lib/protocolo.js';
+
+export const SERVIDOR_PADRAO = 'wss://localhostly.iblabs.io/agent';
+export const RECUO_MIN = 1_000;
+export const RECUO_MAX = 60_000;
+export const JITTER = 0.2;
+
+// A espera antes da tentativa n (0 = a primeira depois da queda): min(max, min·2^n) ± 20 %, nunca acima de max
+// (com a rede de volta, o túnel volta em até um minuto).
+export function recuo(n, { min = RECUO_MIN, max = RECUO_MAX, jitter = JITTER, aleatorio = Math.random } = {}) {
+  const base = Math.min(max, min * 2 ** Math.min(n, 30));
+  return Math.round(Math.min(max, base * (1 + (aleatorio() * 2 - 1) * jitter)));
+}
+
+function paginaErro(alvo, erro) {
+  return (
+    '<!doctype html><html lang="en"><head><meta charset="utf-8"><title>502 · localhostly</title></head>' +
+    '<body style="font:16px/1.5 system-ui,sans-serif;max-width:36rem;margin:15vh auto;padding:0 1rem">' +
+    `<h1>502 · Local app unreachable</h1><p>localhostly could not reach <code>http://${alvo}</code>` +
+    ` (${String(erro.code ?? erro.message).replace(/[<>&]/g, '')}). Is it running?</p></body></html>\n`
+  );
+}
+
+function mesmaLista(a, b) {
+  return Array.isArray(a) && a.length === b.length && a.every((e, i) => e === b[i]);
+}
+
+// alvo: { host, porta } do app local; hostCabecalho: o Host que o app recebe (null = o original).
+export class Tunel extends EventEmitter {
+  constructor({
+    servidor = SERVIDOR_PADRAO,
+    token = null,
+    alvo,
+    hostCabecalho = null,
+    senha = null,
+    // a lista do --allow (textos normalizados por lib/permitidos.js), ou null: o túnel aberto a todos
+    allow = null,
+    reconectar = true,
+    recuoMin = RECUO_MIN,
+    recuoMax = RECUO_MAX,
+    silencioMs = 90_000,
+    handshakeMs = 15_000,
+    // a sessão de antes ({ nome, tokenSessao }): a primeira conexão já pede o mesmo nome
+    sessao = null,
+    // recusado pelo servidor (sem token, limite de túneis…): tenta de novo no recuo em vez de parar (o serviço)
+    insistir = false,
+  }) {
+    super();
+    this.servidor = servidor;
+    this.token = token;
+    this.alvo = alvo;
+    this.hostCabecalho = hostCabecalho;
+    this.senha = senha;
+    this.allow = Array.isArray(allow) && allow.length ? [...allow] : null;
+    this.reconectar = reconectar;
+    this.silencioMs = silencioMs;
+    this.handshakeMs = handshakeMs;
+    this.recuoMin = recuoMin;
+    this.recuoMax = recuoMax;
+    this.insistir = insistir;
+    this.tentativas = 0; // falhas seguidas desde o último "ready"
+    // { nome, tokenSessao } do último "ready": a reconexão retoma o mesmo nome
+    this.sessao = sessao?.nome && sessao?.tokenSessao ? { nome: sessao.nome, tokenSessao: sessao.tokenSessao } : null;
+    this.fechado = false;
+    this.nome = null;
+    this.url = null;
+    this.ws = null;
+    this.agenteHttp = new http.Agent({ keepAlive: true });
+    this.timerReconexao = null;
+  }
+
+  get enderecoLocal() {
+    const h = this.alvo.host.includes(':') ? `[${this.alvo.host}]` : this.alvo.host;
+    return `${h}:${this.alvo.porta}`;
+  }
+
+  abrir() {
+    this.#conectar();
+    return this;
+  }
+
+  // Espera o primeiro "ready" (ou o erro do servidor).
+  pronto() {
+    if (this.nome) return Promise.resolve({ nome: this.nome, url: this.url });
+    return new Promise((resolve, reject) => {
+      const ok = (info) => {
+        this.off('recusado', falha);
+        resolve(info);
+      };
+      const falha = (erro) => {
+        this.off('pronto', ok);
+        reject(erro);
+      };
+      this.once('pronto', ok);
+      this.once('recusado', falha);
+    });
+  }
+
+  fechar() {
+    this.fechado = true;
+    clearTimeout(this.timerReconexao);
+    this.ws?.terminate();
+    this.agenteHttp.destroy();
+  }
+
+  #conectar() {
+    // o prazo do aperto de mão: com a rede voltando, um SYN perdido não segura a tentativa por minutos
+    const ws = new WebSocket(this.servidor, {
+      perMessageDeflate: false,
+      maxPayload: 1024 * 1024,
+      handshakeTimeout: this.handshakeMs,
+    });
+    this.ws = ws;
+    const canal = new Canal(ws);
+    let recusado = false;
+    let aceito = false; // o "ready" valeu: só então as requisições chegam ao app local
+    const pedido = this.sessao?.nome ?? null;
+    let silencio = null;
+    const vigiar = () => {
+      clearTimeout(silencio);
+      silencio = setTimeout(() => ws.terminate(), this.silencioMs);
+    };
+
+    ws.on('open', () => {
+      vigiar();
+      canal.enviarControle({
+        t: 'hello',
+        token: this.token,
+        nome: this.sessao?.nome ?? null,
+        tokenSessao: this.sessao?.tokenSessao ?? null,
+        host: this.hostCabecalho,
+        password: this.senha,
+        allow: this.allow,
+      });
+    });
+    ws.on('ping', vigiar);
+    ws.on('message', vigiar);
+    ws.on('error', (erro) => this.emit('aviso', erro));
+    canal.on('invalido', () => ws.terminate());
+    canal.on('controle', (msg) => {
+      if (msg.t === 'ready') {
+        // pediu --allow e o servidor não devolveu a mesma lista (o servidor de antes ignora o campo): o túnel
+        // estaria aberto a todos, então fecha em vez de seguir
+        if (this.allow && !mesmaLista(msg.allow, this.allow)) {
+          recusado = true;
+          const erro = new Error('this server does not support --allow; update the server or remove --allow');
+          erro.codigo = 'allow_unsupported';
+          this.emit('recusado', erro);
+          ws.terminate();
+          return;
+        }
+        aceito = true;
+        this.tentativas = 0;
+        this.nome = msg.nome;
+        this.url = msg.url;
+        this.sessao = msg.tokenSessao ? { nome: msg.nome, tokenSessao: msg.tokenSessao } : null;
+        // pediu um nome e veio outro (a reserva acabou, o servidor reiniciou): segue com o novo e avisa
+        if (pedido && pedido !== msg.nome) this.emit('nome_trocado', { de: pedido, para: msg.nome });
+        this.emit('pronto', {
+          nome: msg.nome,
+          url: msg.url,
+          retomado: Boolean(msg.retomado),
+          tokenSessao: msg.tokenSessao ?? null,
+        });
+      } else if (msg.t === 'erro') {
+        recusado = true;
+        const erro = new Error(msg.mensagem || msg.codigo);
+        erro.codigo = msg.codigo;
+        this.emit('recusado', erro);
+      }
+    });
+    canal.aoAbrir = (quadro) => {
+      if (!aceito) return;
+      if (quadro.tipo === TIPO.REQ_INICIO) this.#requisicao(canal, quadro);
+      else this.#websocket(canal, quadro);
+    };
+    ws.on('close', () => {
+      clearTimeout(silencio);
+      const tinhaNome = this.nome;
+      this.nome = null;
+      this.url = null;
+      if (this.fechado) return;
+      if (tinhaNome) this.emit('caiu', { nome: tinhaNome });
+      if ((recusado && !this.insistir) || !this.reconectar) {
+        this.emit('fim');
+        return;
+      }
+      const espera = recuo(this.tentativas++, { min: this.recuoMin, max: this.recuoMax });
+      this.emit('reconectando', { emMs: espera, tentativa: this.tentativas });
+      this.timerReconexao = setTimeout(() => this.#conectar(), espera);
+    });
+  }
+
+  #requisicao(canal, { id, payload }) {
+    const inicio = performance.now();
+    const { metodo, caminho, cabecalhos = [] } = payload;
+    const remetente = new Remetente(canal, id, TIPO.RES_CORPO, TIPO.RES_FIM);
+    let respondeu = false;
+    let acabou = false;
+    let status = 0;
+
+    const terminar = () => {
+      if (acabou) return;
+      acabou = true;
+      remetente.encerrar();
+      canal.soltar(id);
+      this.emit('requisicao', { metodo, caminho, status, ms: Math.round(performance.now() - inicio) });
+    };
+
+    const local = http.request({
+      host: this.alvo.host,
+      port: this.alvo.porta,
+      method: metodo,
+      path: caminho,
+      headers: cabecalhos,
+      agent: this.agenteHttp,
+    });
+
+    canal.registrar(id, {
+      quadro: ({ tipo, payload: p }) => {
+        if (tipo === TIPO.REQ_CORPO) entregar(local, p, canal, id);
+        else if (tipo === TIPO.REQ_FIM) local.end();
+        else if (tipo === TIPO.JANELA) remetente.credito(p);
+        else if (tipo === TIPO.ABORTAR) {
+          status = status || 499;
+          local.destroy();
+          terminar();
+        }
+      },
+      fechou: () => {
+        local.destroy();
+        terminar();
+      },
+    });
+
+    local.on('response', (res) => {
+      respondeu = true;
+      status = res.statusCode;
+      canal.enviar(TIPO.RES_INICIO, id, {
+        status: res.statusCode,
+        mensagem: res.statusMessage,
+        cabecalhos: filtrar(res.rawHeaders),
+      });
+      remetente.ligar(res);
+      res.on('end', terminar);
+      res.on('error', () => {
+        if (!acabou) canal.enviar(TIPO.ABORTAR, id, { motivo: 'local' });
+        terminar();
+      });
+    });
+
+    local.on('error', (erro) => {
+      if (acabou) return;
+      if (!respondeu) {
+        status = 502;
+        const corpo = Buffer.from(paginaErro(this.enderecoLocal, erro));
+        canal.enviar(TIPO.RES_INICIO, id, {
+          status: 502,
+          cabecalhos: ['Content-Type', 'text/html; charset=utf-8', 'Content-Length', String(corpo.length)],
+        });
+        canal.enviar(TIPO.RES_CORPO, id, corpo);
+        canal.enviar(TIPO.RES_FIM, id);
+      } else {
+        canal.enviar(TIPO.ABORTAR, id, { motivo: 'local' });
+      }
+      terminar();
+    });
+  }
+
+  #websocket(canal, { id, payload }) {
+    const inicio = performance.now();
+    const { caminho = '/', cabecalhos = [] } = payload;
+    const protocolos = (valor(cabecalhos, 'sec-websocket-protocol') ?? '')
+      .split(',')
+      .map((p) => p.trim())
+      .filter(Boolean);
+    const headers = paraObjeto(sem(cabecalhos, ['sec-websocket-protocol']));
+    let aberto = false;
+    let acabou = false;
+
+    const terminar = (status) => {
+      if (acabou) return;
+      acabou = true;
+      canal.soltar(id);
+      if (!aberto) {
+        this.emit('requisicao', { metodo: 'WS', caminho, status, ms: Math.round(performance.now() - inicio) });
+      }
+    };
+
+    const local = new WebSocket(`ws://${this.enderecoLocal}${caminho}`, protocolos, {
+      headers,
+      perMessageDeflate: false,
+    });
+
+    canal.registrar(id, {
+      quadro: ({ tipo, payload: p }) => {
+        if (tipo === TIPO.WS_DADO) {
+          if (local.readyState === WebSocket.OPEN) local.send(p.dados, { binary: p.binario });
+        } else if (tipo === TIPO.WS_FECHAR) {
+          acabou = true;
+          canal.soltar(id);
+          if (codigoEnviavel(p.codigo)) local.close(p.codigo, String(p.motivo ?? '').slice(0, 120));
+          else local.close();
+        } else if (tipo === TIPO.ABORTAR) {
+          local.terminate();
+          terminar(499);
+        }
+      },
+      fechou: () => {
+        local.terminate();
+        terminar(499);
+      },
+    });
+
+    local.on('open', () => {
+      aberto = true;
+      canal.enviar(TIPO.RES_INICIO, id, { status: 101, protocolo: local.protocol || null });
+      this.emit('requisicao', { metodo: 'WS', caminho, status: 101, ms: Math.round(performance.now() - inicio) });
+    });
+    local.on('unexpected-response', (req, res) => {
+      if (!acabou) {
+        canal.enviar(TIPO.RES_INICIO, id, { status: res.statusCode, motivo: res.statusMessage });
+        terminar(res.statusCode);
+      }
+      res.resume();
+      req.destroy();
+    });
+    local.on('message', (dados, binario) => {
+      canal.enviar(TIPO.WS_DADO, id, { binario, dados: Buffer.isBuffer(dados) ? dados : Buffer.concat(dados) });
+      segurarWs(local, canal);
+    });
+    local.on('error', (erro) => {
+      if (acabou) return;
+      if (!aberto) canal.enviar(TIPO.RES_INICIO, id, { status: 502, motivo: String(erro.code ?? erro.message) });
+      else canal.enviar(TIPO.WS_FECHAR, id, { codigo: 1011, motivo: 'local error' });
+      terminar(502);
+    });
+    local.on('close', (codigo, motivo) => {
+      if (acabou) return;
+      canal.enviar(TIPO.WS_FECHAR, id, { codigo, motivo: motivo.toString('utf8') });
+      terminar(101);
+    });
+  }
+}
+
+export function abrirTunel(opcoes) {
+  return new Tunel(opcoes).abrir();
+}

package/bin/localhostly.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { principal } from '../agente/cli.js';
+
+process.exitCode = await principal();
+process.exit();

package/lib/cabecalhos.js

@@ -0,0 +1,63 @@
+// Cabeçalhos em lista plana [nome, valor, nome, valor, ...], como o rawHeaders do Node:
+// preserva repetidos (Set-Cookie) e a grafia original.
+
+const SALTO = new Set([
+  'connection',
+  'keep-alive',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'proxy-connection',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+]);
+
+// Tira os de salto (hop-by-hop), os citados no Connection e os extras pedidos.
+export function filtrar(lista, extras = []) {
+  const fora = new Set(extras.map((n) => n.toLowerCase()));
+  for (let i = 0; i < lista.length; i += 2) {
+    if (String(lista[i]).toLowerCase() === 'connection') {
+      for (const n of String(lista[i + 1]).split(',')) {
+        const nome = n.trim().toLowerCase();
+        if (nome) fora.add(nome);
+      }
+    }
+  }
+  const saida = [];
+  for (let i = 0; i + 1 < lista.length; i += 2) {
+    const nome = String(lista[i]);
+    const baixo = nome.toLowerCase();
+    if (SALTO.has(baixo) || fora.has(baixo)) continue;
+    saida.push(nome, String(lista[i + 1]));
+  }
+  return saida;
+}
+
+export function valor(lista, nome) {
+  const alvo = nome.toLowerCase();
+  const achados = [];
+  for (let i = 0; i + 1 < lista.length; i += 2) {
+    if (String(lista[i]).toLowerCase() === alvo) achados.push(String(lista[i + 1]));
+  }
+  return achados.length ? achados.join(', ') : undefined;
+}
+
+export function sem(lista, nomes) {
+  const fora = new Set(nomes.map((n) => n.toLowerCase()));
+  const saida = [];
+  for (let i = 0; i + 1 < lista.length; i += 2) {
+    if (!fora.has(String(lista[i]).toLowerCase())) saida.push(lista[i], lista[i + 1]);
+  }
+  return saida;
+}
+
+// Lista plana -> objeto (repetidos juntados por vírgula), para APIs que só aceitam objeto.
+export function paraObjeto(lista) {
+  const obj = {};
+  for (let i = 0; i + 1 < lista.length; i += 2) {
+    const nome = String(lista[i]).toLowerCase();
+    obj[nome] = nome in obj ? `${obj[nome]}, ${lista[i + 1]}` : String(lista[i + 1]);
+  }
+  return obj;
+}

package/lib/canal.js

@@ -0,0 +1,87 @@
+// O canal: um WebSocket entre servidor e agente com vários fluxos (ids) em voo.
+import { EventEmitter } from 'node:events';
+import WebSocket from 'ws';
+import { codificar, decodificar, TIPO } from './protocolo.js';
+
+const ABRE_FLUXO = new Set([TIPO.REQ_INICIO, TIPO.WS_ABRIR]);
+
+export class Canal extends EventEmitter {
+  constructor(ws) {
+    super();
+    this.ws = ws;
+    this.fluxos = new Map();
+    this.proximoId = 1;
+    this.aoAbrir = null; // (quadro) => void, no lado que recebe pedidos (o agente)
+    ws.on('message', (dados, binario) => this.#receber(dados, binario));
+    ws.on('close', () => this.#fechou());
+  }
+
+  get aberto() {
+    return this.ws.readyState === WebSocket.OPEN;
+  }
+
+  get bufferedAmount() {
+    return this.ws.bufferedAmount;
+  }
+
+  novoId() {
+    const id = this.proximoId;
+    this.proximoId = this.proximoId >= 0xffffffff ? 1 : this.proximoId + 1;
+    return id;
+  }
+
+  registrar(id, fluxo) {
+    this.fluxos.set(id, fluxo);
+  }
+
+  soltar(id) {
+    this.fluxos.delete(id);
+  }
+
+  enviar(tipo, id, payload) {
+    if (!this.aberto) return false;
+    this.ws.send(codificar(tipo, id, payload), { binary: true });
+    return true;
+  }
+
+  enviarControle(msg) {
+    if (!this.aberto) return false;
+    this.ws.send(JSON.stringify(msg));
+    return true;
+  }
+
+  #receber(dados, binario) {
+    if (!binario) {
+      let msg;
+      try {
+        msg = JSON.parse(dados.toString('utf8'));
+      } catch {
+        this.emit('invalido', new Error('controle que não é JSON'));
+        return;
+      }
+      this.emit('controle', msg);
+      return;
+    }
+    let quadro;
+    try {
+      quadro = decodificar(dados);
+    } catch (erro) {
+      this.emit('invalido', erro);
+      return;
+    }
+    const fluxo = this.fluxos.get(quadro.id);
+    if (fluxo) {
+      fluxo.quadro(quadro);
+    } else if (ABRE_FLUXO.has(quadro.tipo) && this.aoAbrir) {
+      this.aoAbrir(quadro);
+    }
+    // quadro de id que já acabou (janela atrasada, corpo depois do abortar): ignorado
+  }
+
+  #fechou() {
+    const fluxos = [...this.fluxos.values()];
+    this.fluxos.clear();
+    for (const fluxo of fluxos) fluxo.fechou?.();
+    this.emit('fechou');
+  }
+}

package/lib/fluxo.js

@@ -0,0 +1,100 @@
+// Controle de fluxo: o corpo nunca fica inteiro em memória.
+//
+// Por id: quem manda tem JANELA_INICIAL bytes de crédito; o receptor devolve o crédito
+// (quadro JANELA) só quando o pedaço foi entregue ao destino (o callback do write),
+// então um visitante lento ou um app local lento seguram só o próprio fluxo.
+// No canal inteiro: a fonte pausa quando o WebSocket acumula mais de ALTO bytes no
+// buffer de saída e retoma abaixo de BAIXO.
+import { PEDACO_MAX, TIPO } from './protocolo.js';
+
+export const JANELA_INICIAL = 2 * 1024 * 1024;
+export const ALTO = 4 * 1024 * 1024;
+export const BAIXO = 1024 * 1024;
+const ESPERA_MS = 10;
+
+export class Remetente {
+  constructor(canal, id, tipoCorpo, tipoFim) {
+    this.canal = canal;
+    this.id = id;
+    this.tipoCorpo = tipoCorpo;
+    this.tipoFim = tipoFim;
+    this.saldo = JANELA_INICIAL;
+    this.fonte = null;
+    this.parado = false;
+    this.encerrado = false;
+    this.timer = null;
+  }
+
+  ligar(fonte) {
+    this.fonte = fonte;
+    fonte.on('data', (pedaco) => this.#dados(pedaco));
+    fonte.on('end', () => {
+      if (!this.encerrado) this.canal.enviar(this.tipoFim, this.id);
+    });
+  }
+
+  credito(n) {
+    this.saldo += n;
+    this.#tentarRetomar();
+  }
+
+  encerrar() {
+    this.encerrado = true;
+    clearTimeout(this.timer);
+    this.timer = null;
+  }
+
+  #dados(pedaco) {
+    if (this.encerrado) return;
+    for (let i = 0; i < pedaco.length; i += PEDACO_MAX) {
+      const parte = pedaco.subarray(i, i + PEDACO_MAX);
+      this.canal.enviar(this.tipoCorpo, this.id, parte);
+      this.saldo -= parte.length;
+    }
+    if (this.saldo <= 0 || this.canal.bufferedAmount > ALTO) {
+      if (!this.parado) {
+        this.parado = true;
+        this.fonte.pause();
+      }
+      this.#tentarRetomar();
+    }
+  }
+
+  #tentarRetomar() {
+    if (!this.parado || this.encerrado || this.saldo <= 0) return;
+    if (this.canal.bufferedAmount > BAIXO) {
+      if (!this.timer) {
+        this.timer = setTimeout(() => {
+          this.timer = null;
+          this.#tentarRetomar();
+        }, ESPERA_MS);
+      }
+      return;
+    }
+    this.parado = false;
+    this.fonte.resume();
+  }
+}
+
+// Entrega um pedaço ao destino e devolve o crédito quando ele saiu.
+export function entregar(destino, pedaco, canal, id) {
+  if (destino.destroyed || destino.writableEnded) return;
+  destino.write(pedaco, (erro) => {
+    if (!erro) canal.enviar(TIPO.JANELA, id, pedaco.length);
+  });
+}
+
+// Mensagens de WebSocket: pausa a fonte enquanto o canal está cheio.
+export function segurarWs(ws, canal) {
+  if (canal.bufferedAmount <= ALTO || ws.isPaused) return;
+  ws.pause();
+  const conferir = () => {
+    if (ws.readyState > 1) return;
+    if (canal.aberto && canal.bufferedAmount > BAIXO) {
+      setTimeout(conferir, ESPERA_MS);
+      return;
+    }
+    ws.resume();
+  };
+  setTimeout(conferir, ESPERA_MS);
+}

package/lib/permitidos.js

@@ -0,0 +1,85 @@
+// A lista de endereços que podem visitar o túnel (--allow): IPs e faixas (CIDR), IPv4 e IPv6. O agente a confere
+// antes de abrir e o servidor de novo no hello; os dois normalizam pela mesma regra, então o eco do "ready" é igual
+// à lista que o agente mandou.
+import net from 'node:net';
+
+export const MAX_PERMITIDOS = 64;
+
+export class ErroLista extends Error {
+  constructor(mensagem, entrada) {
+    super(mensagem);
+    this.entrada = entrada;
+  }
+}
+
+// "::ffff:1.2.3.4" (IPv4 mapeado em IPv6, como o socket de dupla pilha mostra) → "1.2.3.4".
+function semMapeado(ip) {
+  const m = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(ip);
+  return m && net.isIPv4(m[1]) ? m[1] : ip;
+}
+
+// Um endereço na forma canônica: { ip, familia: 'ipv4' | 'ipv6' } ou null.
+export function lerIp(texto) {
+  const ip = semMapeado(String(texto ?? '').trim());
+  const versao = net.isIP(ip);
+  if (versao === 4) return { ip, familia: 'ipv4' };
+  if (versao === 6) return { ip: new net.SocketAddress({ address: ip, family: 'ipv6' }).address, familia: 'ipv6' };
+  return null;
+}
+
+// Uma entrada: "203.0.113.7", "10.0.0.0/8", "2001:db8::/32" → { ip, bits, familia, texto }; inválida → null.
+export function lerEntrada(texto) {
+  const t = String(texto ?? '').trim();
+  const m = /^([^/]+)(?:\/(\d{1,3}))?$/.exec(t);
+  if (!m) return null;
+  const end = lerIp(m[1]);
+  if (!end) return null;
+  const max = end.familia === 'ipv4' ? 32 : 128;
+  // o mapeado com prefixo de IPv6 (/96 + n) vira o prefixo de IPv4
+  let bits = m[2] === undefined ? max : Number(m[2]);
+  if (m[2] !== undefined && end.familia === 'ipv4' && m[1].includes(':')) bits -= 96;
+  if (!Number.isInteger(bits) || bits < 0 || bits > max) return null;
+  return { ip: end.ip, bits, familia: end.familia, texto: bits === max ? end.ip : `${end.ip}/${bits}` };
+}
+
+// texto ("a,b") ou lista de textos (cada um pode ter vírgulas) → a lista sem repetidas, na ordem; vazia → [].
+// Lança ErroLista com a primeira entrada inválida ou com mais de MAX_PERMITIDOS.
+export function normalizarLista(valor) {
+  const pedacos = (Array.isArray(valor) ? valor : [valor])
+    .flatMap((v) => String(v ?? '').split(','))
+    .map((p) => p.trim())
+    .filter(Boolean);
+  const lista = [];
+  const vistos = new Set();
+  for (const p of pedacos) {
+    const e = lerEntrada(p);
+    if (!e) throw new ErroLista(`not an IP address or range: ${p}`, p);
+    if (vistos.has(e.texto)) continue;
+    vistos.add(e.texto);
+    lista.push(e);
+  }
+  if (lista.length > MAX_PERMITIDOS) throw new ErroLista(`too many addresses: ${lista.length} (at most ${MAX_PERMITIDOS})`, null);
+  return lista;
+}
+
+export function textoDaLista(lista) {
+  return (lista ?? []).map((e) => e.texto);
+}
+
+// O conferidor de uma lista normalizada: (ip) → true se o endereço está nela.
+export function criarConferidor(lista) {
+  const bloco = new net.BlockList();
+  for (const e of lista) {
+    const max = e.familia === 'ipv4' ? 32 : 128;
+    if (e.bits === max) bloco.addAddress(e.ip, e.familia);
+    else bloco.addSubnet(e.ip, e.bits, e.familia);
+  }
+  return (ip) => {
+    const end = lerIp(ip);
+    return Boolean(end) && bloco.check(end.ip, end.familia);
+  };
+}
+
+export function ipPermitido(ip, lista) {
+  return criarConferidor(lista)(ip);
+}