localhostly 1.0.0 → 1.1.0

package/README.md

@@ -35,6 +35,7 @@ localhostly 3000                        # expose http://127.0.0.1:3000
 localhostly http 3000 --password        # visitors must type a password (a random one is shown)
 localhostly http 3000 --password s3cret # ...or your own
 localhostly http 8080 --host myapp.test # forward to another local address; the app receives it as Host
+localhostly http 3000 --allow 203.0.113.7,10.0.0.0/8 # only these IP addresses or ranges get in; others see 403
 ```
 
 The terminal shows the public URL and every request live. HTTP, streaming responses and WebSockets all go through.
@@ -43,6 +44,10 @@ Stop with Ctrl+C.
 The first time a browser opens your URL it sees a short warning page (it protects against phishing); API clients,
 webhooks and `curl` never see it, and a browser can skip it by sending the header `X-Localhostly-Skip-Warning`.
 
+With `--allow` (IPv4 or IPv6 addresses and CIDR ranges, comma-separated or repeated, up to 64) only those
+addresses reach your app, without the warning page; every other address gets a 403 page that shows it, WebSockets
+included. `--allow` and `--password` together require both. `localhostly service install` takes `--allow` too.
+
 ## Keep it always on
 
 ```sh
@@ -56,7 +61,7 @@ with `npm i -g` first — a copy run by `npx` lives in a temporary folder.
 
 ## Free plan limits
 
-2 tunnels at a time, 150 requests per minute and 25 GiB per month per account.
+2 tunnels at a time, 1000 requests per minute and 25 GiB per month per account.
 
 ## All options
 

package/agente/cli.js

@@ -4,6 +4,7 @@ import { randomInt } from 'node:crypto';
 import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
+import { ErroLista, normalizarLista, textoDaLista } from '../lib/permitidos.js';
 import * as servico from './servico/index.js';
 import { criarLog, criarTela } from './tela.js';
 import { SERVIDOR_PADRAO, Tunel } from './tunel.js';
@@ -30,6 +31,8 @@ Options:
   --password [value]      ask visitors for a password (the browser shows a login box; any user name);
                           without a value, a random one is created and shown here
   --password-file <file>  the same, with the password read from a file
+  --allow <ip[,ip|cidr]>  only these IP addresses or ranges can reach the tunnel; everyone else gets 403
+                          (comma-separated, e.g. 203.0.113.7,10.0.0.0/8; use more than once to add)
   --service               service mode: one log line per event, no live table, never gives up
   --home <dir>            where the token and the service state live (default ~/.localhostly,
                           or $LOCALHOSTLY_HOME)
@@ -90,6 +93,7 @@ export function lerAlvo(texto, portaPadrao) {
 }
 
 export function lerArgumentos(argv) {
+  const allow = [];
   const opcoes = {
     comando: null,
     posicionais: [],
@@ -97,6 +101,7 @@ export function lerArgumentos(argv) {
     servidor: null,
     senha: false,
     arquivoSenha: null,
+    allow: null, // a lista normalizada (textos), ou null sem --allow
     servico: false,
     home: null,
   };
@@ -128,11 +133,25 @@ export function lerArgumentos(argv) {
     else if (chave === '--server') opcoes.servidor = valorDe();
     else if (chave === '--password') opcoes.senha = valorDaSenha();
     else if (chave === '--password-file') opcoes.arquivoSenha = valorDe();
+    else if (chave === '--allow') {
+      const texto = valorDe();
+      if (!texto.trim()) throw erroDeUso(`${chave} needs a value: an IP address or range, e.g. --allow 203.0.113.7`);
+      allow.push(texto);
+    }
     else if (chave === '--service') opcoes.servico = true;
     else if (chave === '--home') opcoes.home = valorDe();
     else if (chave.startsWith('-')) throw erroDeUso(`unknown option: ${chave}`);
     else opcoes.posicionais.push(a);
   }
+  if (allow.length) {
+    try {
+      opcoes.allow = textoDaLista(normalizarLista(allow));
+    } catch (erro) {
+      if (!(erro instanceof ErroLista)) throw erro;
+      throw erroDeUso(`invalid --allow: ${erro.message} (use IP addresses or ranges, e.g. --allow 203.0.113.7,10.0.0.0/8)`);
+    }
+    if (!opcoes.allow.length) throw erroDeUso('--allow needs at least one IP address or range');
+  }
   if (!opcoes.comando) {
     const [primeiro] = opcoes.posicionais;
     if (COMANDOS.includes(primeiro)) opcoes.comando = opcoes.posicionais.shift();
@@ -169,7 +188,7 @@ function alvoDe(opcoes, uso) {
 }
 
 const USO_SERVICO =
-  'usage: localhostly service install <port> [--host h[:p]] [--password [value]] [--server url]\n' +
+  'usage: localhostly service install <port> [--host h[:p]] [--password [value]] [--allow ip[,ip|cidr]] [--server url]\n' +
   '       localhostly service status\n' +
   '       localhostly service uninstall';
 
@@ -204,11 +223,12 @@ export async function comandoServico(
       }
       const servidor = opcoes.servidor || env.LOCALHOSTLY_SERVER || config.server || null;
       const antes = Date.now();
-      const r = api.instalar({ porta, host: opcoes.host, servidor, senha, home }, { plataforma, env });
+      const r = api.instalar({ porta, host: opcoes.host, servidor, senha, allow: opcoes.allow, home }, { plataforma, env });
       saida.write(`Installed the localhostly ${nome}: ${r.arquivo}\n`);
       saida.write('It starts with the computer, reconnects by itself and keeps the same name.\n');
       if (gerada) saida.write(`Password: ${senha} (any user name)\n`);
       else if (senha) saida.write('Password protected (any user name).\n');
+      if (opcoes.allow) saida.write(`Allowed: ${opcoes.allow.join(', ')} (other addresses get 403)\n`);
       const fim = Date.now() + esperarUrlMs;
       let tunel = null;
       while (Date.now() < fim) {
@@ -306,6 +326,7 @@ export async function principal(argv = process.argv.slice(2), { env = process.en
     alvo,
     hostCabecalho: opcoes.host,
     senha,
+    allow: opcoes.allow,
     sessao: modoServico ? servico.lerEstado(home) : null,
     insistir: modoServico,
   });
@@ -318,7 +339,7 @@ export async function principal(argv = process.argv.slice(2), { env = process.en
         tela.aviso(`could not save the tunnel state in ${home}: ${erro.code ?? erro.message}`);
       }
     }
-    tela.pronto({ url, alvo: tunel.enderecoLocal, senha: senha && (gerada ? senha : true), retomado });
+    tela.pronto({ url, alvo: tunel.enderecoLocal, senha: senha && (gerada ? senha : true), retomado, permitidos: opcoes.allow });
   });
   tunel.on('nome_trocado', ({ de, para }) =>
     tela.aviso(`name changed: ${de} -> ${para} (the old name was released while the tunnel was offline)`),

package/agente/servico/comum.js

@@ -14,14 +14,16 @@ export function executar(programa, args = [], opcoes = {}) {
 }
 
 // O argv do agente que o serviço roda: [node, bin/localhostly.js, 'http', porta, '--service', ...]. A senha nunca vai
-// na linha de comando (o `ps` a mostraria a qualquer usuário): só o caminho do arquivo 0600 que a guarda.
-export function comandoDoAgente({ exe, porta, host = null, servidor = null, home, arquivoSenha = null }) {
+// na linha de comando (o `ps` a mostraria a qualquer usuário): só o caminho do arquivo 0600 que a guarda. A lista
+// do --allow (não é segredo) vai como "--allow a,b".
+export function comandoDoAgente({ exe, porta, host = null, servidor = null, home, arquivoSenha = null, allow = null }) {
   if (!Array.isArray(exe) || exe.length === 0) throw new Error('exe: the agent command is missing');
   if (!Number.isInteger(porta) || porta < 1 || porta > 65535) throw new Error(`invalid port: ${porta}`);
   const args = [...exe, 'http', String(porta), '--service', '--home', home];
   if (host) args.push('--host', host);
   if (servidor) args.push('--server', servidor);
   if (arquivoSenha) args.push('--password-file', arquivoSenha);
+  if (allow?.length) args.push('--allow', allow.join(','));
   return args;
 }
 

package/agente/servico/index.js

@@ -61,11 +61,13 @@ export function gravarEstado(home, { nome, tokenSessao, url }, agora = new Date(
   return arquivo;
 }
 
-// opcoes: { porta, host, servidor, senha (texto ou null), home, exe }
+// opcoes: { porta, host, servidor, senha (texto ou null), allow (a lista normalizada do --allow, ou null), home, exe }
 export function instalar(opcoes, { plataforma = process.platform, casa = homedir(), env = process.env, exec = executar, uid } = {}) {
   const s = sistema(plataforma);
-  const { porta, host = null, servidor = null, senha = null, home, exe = exePadrao() } = opcoes;
-  if (!Number.isInteger(porta)) throw new ErroServico('usage: localhostly service install <port> [--host h[:p]] [--password [value]]');
+  const { porta, host = null, servidor = null, senha = null, allow = null, home, exe = exePadrao() } = opcoes;
+  if (!Number.isInteger(porta)) {
+    throw new ErroServico('usage: localhostly service install <port> [--host h[:p]] [--password [value]] [--allow ip[,ip|cidr]]');
+  }
   mkdirSync(home, { recursive: true, mode: 0o700 });
   let arquivo = null;
   if (senha) {
@@ -77,7 +79,7 @@ export function instalar(opcoes, { plataforma = process.platform, casa = homedir
   } else {
     rmSync(arquivoSenha(home), { force: true });
   }
-  const comando = comandoDoAgente({ exe, porta, host, servidor, home, arquivoSenha: arquivo });
+  const comando = comandoDoAgente({ exe, porta, host, servidor, home, arquivoSenha: arquivo, allow });
   const r = s.instalar({ comando, porta, home }, { casa, env, exec, home, ...(uid === undefined ? {} : { uid }) });
   // o npx roda de uma pasta de cache que pode sumir: o serviço apontaria para um caminho morto
   if (exe.some((parte) => /[\\/]_npx[\\/]/.test(parte))) {

package/agente/tela.js

@@ -21,9 +21,11 @@ export function criarTela(saida = process.stdout, { cor = Boolean(saida.isTTY) &
       linha(pintar('cinza', `connecting to ${servidor}…`));
     },
     // senha: o texto (a gerada, que só esta tela mostra), true (a que o usuário escolheu) ou nada.
-    pronto({ url, alvo, senha = null }) {
+    // permitidos: a lista do --allow (só esses endereços entram) ou nada.
+    pronto({ url, alvo, senha = null, permitidos = null }) {
       linha('');
       linha(`${pintar('negrito', url)} → http://${alvo}`);
+      if (permitidos?.length) linha(`Allowed: ${pintar('negrito', permitidos.join(', '))} ${pintar('cinza', '(other addresses get 403)')}`);
       if (typeof senha === 'string') linha(`Password: ${pintar('negrito', senha)} ${pintar('cinza', '(any user name)')}`);
       else if (senha) linha(pintar('cinza', 'Password protected (any user name).'));
       linha(pintar('cinza', 'Ctrl+C to stop. Requests:'));
@@ -53,8 +55,11 @@ export function criarLog(saida = process.stdout, { relogio = () => new Date() }
     conectando(servidor) {
       linha(`connecting to ${servidor}`);
     },
-    pronto({ url, alvo, senha = null, retomado = false }) {
-      linha(`online ${url} -> http://${alvo}${retomado ? ' (same name)' : ''}${senha ? ' (password protected)' : ''}`);
+    pronto({ url, alvo, senha = null, retomado = false, permitidos = null }) {
+      linha(
+        `online ${url} -> http://${alvo}${retomado ? ' (same name)' : ''}${senha ? ' (password protected)' : ''}` +
+          `${permitidos?.length ? ` (allowed: ${permitidos.join(',')})` : ''}`,
+      );
     },
     requisicao() {},
     aviso(texto) {

package/agente/tunel.js

@@ -29,6 +29,10 @@ function paginaErro(alvo, erro) {
   );
 }
 
+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({
@@ -37,6 +41,8 @@ export class Tunel extends EventEmitter {
     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,
@@ -53,6 +59,7 @@ export class Tunel extends EventEmitter {
     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;
@@ -114,6 +121,7 @@ export class Tunel extends EventEmitter {
     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 = () => {
@@ -130,6 +138,7 @@ export class Tunel extends EventEmitter {
         tokenSessao: this.sessao?.tokenSessao ?? null,
         host: this.hostCabecalho,
         password: this.senha,
+        allow: this.allow,
       });
     });
     ws.on('ping', vigiar);
@@ -138,6 +147,17 @@ export class Tunel extends EventEmitter {
     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;
@@ -158,6 +178,7 @@ export class Tunel extends EventEmitter {
       }
     });
     canal.aoAbrir = (quadro) => {
+      if (!aceito) return;
       if (quadro.tipo === TIPO.REQ_INICIO) this.#requisicao(canal, quadro);
       else this.#websocket(canal, quadro);
     };

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);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "localhostly",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Expose any local port on a public HTTPS URL, behind NAT, without opening ports.",
   "keywords": [
     "tunnel",
@@ -27,10 +27,14 @@
   },
   "scripts": {
     "test": "node --test \"testes/*.test.mjs\"",
-    "servidor": "node server/index.js"
+    "servidor": "node server/index.js",
+    "seo:check": "node scripts/seo/check.mjs"
   },
   "license": "MIT",
   "dependencies": {
     "ws": "^8.22.2"
+  },
+  "devDependencies": {
+    "cheerio": "1.2.0"
   }
 }