# AGENT.md

<!--
  Lido por agentes de codigo (Codex, Claude Code) antes de tarefas neste repo.
  Mantenha curto, operacional e atualizado.
-->

## O que e este projeto

`rato` contem ferramentas Windows via CMD/PowerShell para uso de Cloudflare Access TCP/SOCKS5 com Firefox, sem privilegios de administrador e sem mudar o navegador padrao do Windows.

O foco atual e facilitar o uso por Guilherme e Marina:

- verificar pre-requisitos com `check.cmd`
- abrir login do Cloudflare Access no Firefox limpo, sem proxy
- iniciar `cloud/cloudflared/hehe access tcp` em `127.0.0.1:3443`
- iniciar `ssh -D 1080 -N -p 3443 lucas@127.0.0.1` para criar SOCKS5
- manter a janela aberta enquanto o tunel esta ativo

## Regras obrigatorias

- Nao salvar senha, token, cookie, `cert.pem`, chave ou segredo no repo.
- Nao alterar registro do Windows.
- Nao alterar navegador padrao.
- Nao exigir administrador.
- Nao alterar PATH do sistema.
- Nao tentar burlar antivirus, SmartScreen, proxy institucional ou politica de TI.
- Usar nomes claros e legitimos para scripts e mensagens.
- Tratar Cloudflare/Access/proxy como area sensivel.

## Configuracao padrao

Arquivo principal:

- `config/cloudflare-access.env`

Valores padrao:

- `CLOUDFLARED_HOSTNAME=ssh-rip.beneditoonline.org`
- `ACCESS_TCP_URL=127.0.0.1:3443`
- `SSH_USER=lucas`
- `SSH_HOST=127.0.0.1`
- `SSH_PORT=3443`
- `LOCAL_SOCKS_HOST=127.0.0.1`
- `LOCAL_SOCKS_PORT=1080`
- `BALTA_URL=https://ripp.beneditoonline.org/`
- `FIREFOX_PATH=`
- `CLOUDFLARED_PATH=`
- `SSH_PATH=`

Se `config/cloudflare-access.env` nao existir, scripts podem copiar de `config/cloudflare-access.example.env`.

## Estrutura importante

- `README-GUILHERME-MARINA.md` - instrucoes simples para usuarios leigos
- `configurar.cmd` / `0-configurar.cmd` - configuracao principal por CMD, sem senha
- `configurar.vbs` / `0-configurar.vbs` - caixas de texto opcionais para placeholders nao secretos
- `lib/scan-paths.ps1` - scan de paths em multiplos `config/*.env`, PATH e caminhos comuns
- `check.cmd` - diagnostico simples
- `checar.cmd`, `ligar.cmd`, `ajuda.cmd` - comandos curtos para CMD
- `1-checar.vbs`, `2-ligar.vbs`, `3-ajuda.vbs` - atalhos de duplo clique com janela visivel
- `start-socks.cmd` - inicia tunel via PowerShell
- `start-socks-firefox-login.cmd` - abre Firefox limpo e inicia tunel
- `stop-instructions.txt` - como parar o tunel
- `lib/start-socks.ps1` - logica principal do tunel
- `lib/open-firefox-clean.ps1` - abre Firefox com perfil temporario e proxy desativado
- `lib/detect-firefox.ps1` - deteccao reutilizavel do Firefox

Scripts antigos de instalacao (`install.cmd`, `uninstall.cmd`, `cloudflared-firefox.cmd`, `user-env.cmd`) existem para ferramentas de PATH do usuario. Nao misture esse fluxo com o launcher simples sem verificar impacto.

## Antes de alterar scripts sensiveis

Antes de mudar scripts que mexem com Cloudflare, login, proxy, PATH, ambiente do usuario ou persistencia, explicite:

1. problema encontrado
2. causa provavel
3. arquivos que pretende alterar
4. risco da mudanca
5. validacao planejada
6. rollback simples

Para mudancas pequenas e claramente corretivas, pode executar direto, mas registre a validacao no final.

## Validacao minima

Em Linux, nao executar os launchers reais se isso puder iniciar login/tunel. Validar estaticamente:

```bash
git diff --check
rg -n "SetEnvironmentVariable|reg |AutoRun|cert\\.pem|token|cookie|senha|segredo" .
rg -n "%~dp0|%\\*|powershell.exe -NoProfile -ExecutionPolicy Bypass -File" .
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\lib\scan-paths.ps1
```

Se PowerShell estiver disponivel:

```bash
pwsh -NoProfile -Command "[System.Management.Automation.Language.Parser]::ParseFile('lib/start-socks.ps1',[ref]`$null,[ref]`$null) | Out-Null"
```

No Windows, quando for seguro testar:

```cmd
check.cmd
start-socks-firefox-login.cmd
```

Nao considerar pronto sem revisar:

- aspas em caminhos com espaco
- `%~dp0`
- repasse de argumentos
- ausencia de admin/registro
- ausencia de segredo persistido no repo
- comportamento quando Firefox ou cloudflared nao existem

## Claude como revisor sensivel

- Em tarefas sensiveis, use o Claude automaticamente como revisor adicional pelo terminal quando houver credencial local configurada.
- Tarefas sensiveis incluem Cloudflare, Access, proxy, autenticacao, scripts de instalacao, PATH, persistencia, seguranca e qualquer mudanca que possa gravar segredo.
- Se existir `scripts/ask-claude.sh`, use esse wrapper para chamar `claude -p` sem interacao.
- A credencial local, quando existir, deve vir de `~/.config/claude-code/anthropic.env`, com `ANTHROPIC_API_KEY` ou `ANTHROPIC_AUTH_TOKEN`.
- Nao automatize login por navegador, captcha, MFA ou OAuth.
- Nao salve senha da conta Claude em arquivo.
- Nunca imprima, registre em log ou versione chave, token ou senha.
- Se a credencial/script nao existir, informe a ausencia e siga com a melhor revisao local possivel.

## Cloudflare / Firefox

- O Firefox usado para login deve abrir sem proxy.
- `lib/open-firefox-clean.ps1` deve criar/atualizar `user.js` com `user_pref("network.proxy.type", 0);`.
- Prefira perfil temporario ou separado para login.
- O launcher deve orientar o usuario a clicar em Accept/Login e deixar a janela aberta.
- O launcher nao deve mudar navegador padrao nem registro.
- Se `cloudflared` imprimir URL de login e o navegador nao abrir corretamente, mostre instrucao para copiar a URL no Firefox limpo.

## O que nao fazer

- Nao commitar `.env` com segredo. O `.env` padrao deste repo so pode conter valores nao secretos.
- Nao incluir tokens de servico Cloudflare.
- Nao orientar usuario a digitar senha em local especifico no README; se algum programa pedir credencial, ele deve seguir o prompt oficial exibido.
- Nao esconder janelas ou comportamento do usuario.
- Preferir `.cmd` como interface principal. Arquivos `.vbs` podem melhorar caixas de texto, mas devem abrir janela visivel e chamar scripts claros.
- Nao adicionar AutoRun no CMD.
- Nao adicionar instalador com privilegio admin.
- Nao apagar arquivos pessoais do usuario.
- Nao mascarar erro: se nao souber, diga o que precisa verificar.