@dutodev/cli 0.4.1 → 0.4.2

package/README.md

@@ -51,25 +51,47 @@ Todos os túneis sobem juntos, numa única tela. A CLI procura o arquivo na past
 
 ### Host e cabeçalhos
 
-Por padrão, o serviço local recebe o Host público (`web-<usuário>.duto.dev`). Se ele escolhe o que responder pelo Host, como um proxy reverso local ou um app com vários domínios, troque o Host com `host:` e ajuste cabeçalhos com `headers:`:
+Por padrão, o serviço local recebe a requisição como ela chegou da internet: `Host: web-<usuário>.duto.dev`, `X-Forwarded-Proto: https` e os cabeçalhos da Cloudflare (`CF-Connecting-IP` e outros). Na maioria dos apps isso basta. Quando o app decide algo pelo domínio, há duas ferramentas por túnel:
 
 ```yaml
 tunnels:
   loja:
     port: 8080
-    host: loja.meuapp.test      # o serviço recebe este Host
-  painel:
-    port: 8080                  # mesma porta: vale quando cada túnel tem um host
-    host: painel.meuapp.test
-    headers:
-      X-Ambiente: tunel         # acrescenta ou sobrescreve
+    headers:                    # acrescenta ou sobrescreve cabeçalhos
+      X-Forwarded-Host: loja.meuapp.test
       X-Debug: ""               # valor vazio remove o cabeçalho
+  painel:
+    port: 8081
+    host: painel.meuapp.test    # troca o Host que o serviço recebe
 ```
 
-- Com `host:`, o `X-Forwarded-Host` não é enviado, para o app não ver o domínio público. Se quiser enviá-lo, coloque-o em `headers:`.
-- Redirecionamentos voltam com o endereço público: um `Location: http://loja.meuapp.test:8080/login` chega ao navegador como `https://loja-<usuário>.duto.dev/login`. Isso vale também dentro de parâmetros codificados, como o `redirect_uri` de um login OAuth. Para desligar, use `rewrite_redirects: false` no túnel.
-- Na linha de comando: `duto 8080 --host loja.meuapp.test` (e `--no-rewrite-redirects` para desligar a troca).
-- Links dentro das páginas (HTML, JSON) não são reescritos: se o app montar URLs a partir do Host, elas só abrem na sua máquina.
+**Qual usar:**
+
+| Situação | Use | Por quê |
+|---|---|---|
+| Um proxy reverso local (Traefik, Nginx, Caddy) escolhe o serviço pelo Host | `host:` | O proxy só conhece os domínios locais |
+| Vários túneis na mesma porta, um por domínio | `host:` ou `headers:` diferentes em cada um | A porta pode se repetir; cada túnel tem o próprio endereço |
+| O app identifica o domínio ou o cliente pelo `X-Forwarded-Host`, mas monta URLs a partir do `Host` | `headers:` com `X-Forwarded-Host` | O app vê o domínio local e continua gerando links públicos |
+| Login OAuth em que o app calcula o `redirect_uri` sozinho | evite `host:`; tente `headers:` | Veja abaixo |
+
+**O que o `host:` faz:**
+
+- O serviço recebe o Host informado, e o `X-Forwarded-Host` não é enviado. Para enviá-lo assim mesmo, coloque-o em `headers:`.
+- Os redirecionamentos voltam com o endereço público. Um `Location: http://painel.meuapp.test:8081/login` chega ao navegador como `https://painel-<usuário>.duto.dev/login`. Isso vale também dentro de parâmetros codificados no `Location`. Para desligar, use `rewrite_redirects: false` no túnel.
+- Links no corpo das respostas (HTML, JSON) não são reescritos. URLs que o app montar a partir do Host só abrem na sua máquina.
+- Na linha de comando: `duto 8081 --host painel.meuapp.test`, e `--no-rewrite-redirects` para desligar a troca.
+
+**OAuth e `host:`.** No fluxo de autorização por código, o app manda um `redirect_uri` duas vezes: na ida do navegador ao provedor de login e depois, servidor a servidor, ao trocar o código por token. O provedor exige que as duas sejam idênticas. Com `host:`, o app gera as duas com o domínio local. O Duto corrige a primeira, que passa pelo navegador, mas não alcança a segunda, que não passa pelo túnel. O provedor recusa a troca, em geral com `invalid_request` ou `invalid_grant`, e o app costuma voltar ao login em loop (`ERR_TOO_MANY_REDIRECTS`).
+
+Saídas, da mais simples para a mais trabalhosa:
+
+1. Não troque o Host. O app gera o `redirect_uri` com o endereço público nas duas vezes.
+2. Se o app precisa ver o domínio local para outras decisões e lê o `X-Forwarded-Host`, passe o domínio por `headers:` e mantenha o Host público.
+3. Configure no app a URL pública de retorno, se ele permitir.
+
+Em todos os casos, cadastre `https://<nome>-<usuário>.duto.dev/<caminho de retorno>` como URL de retorno no provedor. A comparação costuma ser exata, sem curingas: cada pessoa do time tem o próprio endereço.
+
+**Sobre o `X-Forwarded-*`.** `X-Forwarded-Host`, `X-Forwarded-Proto` e `X-Forwarded-For` são uma convenção antiga entre proxies reversos para contar ao app o que o cliente pediu de verdade. A versão padronizada é o cabeçalho `Forwarded` (RFC 7239), menos usado na prática. Frameworks costumam ler esses cabeçalhos só quando o proxy é marcado como confiável (`trusted proxies`, `trust proxy`, `USE_X_FORWARDED_HOST`), então o efeito de `headers:` depende de como o app está configurado. Por outro lado, se um app lê o `X-Forwarded-Host` sem essa checagem, qualquer cliente pode forjá-lo em produção. Vale garantir que o proxy da frente sobrescreva ou remova esse cabeçalho.
 
 ## A tela
 

package/dist/index.js

@@ -263,7 +263,6 @@ function parseConfig(text, file = CONFIG_FILES[0]) {
     throw fail3('declare os t\xFAneis em "tunnels:", um por linha (ex.: web: 3000).');
   }
   const specs = [];
-  const seen = /* @__PURE__ */ new Map();
   for (const pair of tunnels.items) {
     const raw = isScalar(pair.key) ? String(pair.key.value) : "";
     const line = lineAt(pair.key?.range?.[0]);
@@ -317,16 +316,7 @@ function parseConfig(text, file = CONFIG_FILES[0]) {
         if (value === false) spec.rewriteRedirects = false;
       }
     }
-    const users = seen.get(port) ?? [];
-    const clash = users.find((u) => !u.host || !spec.host || u.host === spec.host);
-    if (clash) {
-      throw fail3(
-        clash.host && clash.host === spec.host ? `a porta ${port} com host ${spec.host} aparece em "${clash.raw}" e em "${raw}"` : `a porta ${port} aparece em "${clash.raw}" e em "${raw}". Para usar a mesma porta, d\xEA um host a cada um.`,
-        line
-      );
-    }
     if (specs.some((s) => s.name === name)) throw fail3(`o nome "${raw}" aparece duas vezes`, line);
-    seen.set(port, [...users, { raw, host: spec.host }]);
     specs.push(spec);
   }
   return specs;
@@ -920,9 +910,9 @@ async function runSession(specs, source, flags) {
   const session = new Session({ api, deviceId: config.deviceId, deviceName: hostname(), cloudflaredPath, source });
   if (wantsUi(flags)) {
     const { runFullscreen } = await import("./fullscreen-5437X7MP.js");
-    process.exit(await runFullscreen(session, specs, "0.4.1"));
+    process.exit(await runFullscreen(session, specs, "0.4.2"));
   }
-  console.log(`${mark()} ${paint("muted", `${"0.4.1"} \xB7 ${source} \xB7 Ctrl+C para encerrar`)}`);
+  console.log(`${mark()} ${paint("muted", `${"0.4.2"} \xB7 ${source} \xB7 Ctrl+C para encerrar`)}`);
   const stopLog = runPlain(session, (l) => console.log(l));
   const stopped = new Promise((resolve) => {
     const onSignal = () => {
@@ -1009,7 +999,7 @@ cli.help(
     body: s.body.replace(/^\s*For more info, run any command with the `--help` flag:/m, "  Mais detalhes de um comando: duto <comando> --help").replace("Display this message", "Mostra esta ajuda").replace("Display version number", "Mostra a vers\xE3o")
   }))
 );
-cli.version("0.4.1");
+cli.version("0.4.2");
 try {
   cli.parse(process.argv, { run: false });
   await cli.runMatchedCommand();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dutodev/cli",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Exponha uma porta local em https://<nome>-<usuário>.duto.dev com um comando.",
   "license": "MIT",
   "type": "module",