numa

# Numa

[![CI](https://github.com/razvandimescu/numa/actions/workflows/ci.yml/badge.svg)](https://github.com/razvandimescu/numa/actions)
[![crates.io](https://img.shields.io/crates/v/numa.svg)](https://crates.io/crates/numa)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**DNS que você possui. Onde quer que você vá.** — [numa.rs](https://numa.rs)

Um resolvedor DNS portátil em um único binário. Bloqueie anúncios em qualquer rede, nomeie seus serviços locais (`frontend.numa`), sobrescreva qualquer hostname com reversão automática e sele cada consulta de saída com **ODoH (RFC 9230)** para que nenhuma parte isolada veja tanto quem você é quanto o que você perguntou — tudo do seu laptop, sem conta na nuvem ou Raspberry Pi. 

Construído do zero em Rust. Zero bibliotecas DNS. Cache, bloqueio de anúncios e domínios de serviços locais prontos para uso. Resolução recursiva opcional a partir dos servidores de nomes raiz com validação completa da cadeia de confiança DNSSEC, além de um listener DNS-over-TLS para conexões de clientes criptografadas (iOS Private DNS, systemd-resolved, etc.). Execute `numa relay` e o mesmo binário se torna também um endpoint ODoH público — a lista curada do DNSCrypt atualmente tem apenas um relay sobrevivente, então cada implantação do Numa expande materialmente o ecossistema. Um binário de ~8MB, tudo embutido. O parser do protocolo de rede foi escrito à mão como projeto de aprendizado; recursos posteriores (resolvedor recursivo, DNSSEC, dashboard) foram construídos com assistência de IA.

![Numa dashboard](https://assets.kitploit.com/production/public/readmes/13090/5d6f10865bf168b1b4d4b8a8223ff961e66cfc2fe7f91754e71f105f2f921cc0.gif)

## Início Rápido

Três formas de começar, da menos à mais comprometedora. Apenas a terceira altera o DNS do seu sistema.

### 1. Experimente no Docker (nada instalado no host)

```bash
docker run -d --name numa -p 127.0.0.1:5553:53/udp -p 127.0.0.1:5553:53/tcp \
  -p 127.0.0.1:5380:5380 ghcr.io/razvandimescu/numa
dig @127.0.0.1 -p 5553 example.com
docker exec numa numa token            # dashboard password
```

Abra `http://localhost:5380` e faça login com qualquer nome de usuário e esse token. A porta 5553 contorna o que já estiver ocupando a 53 no host. `numa.numa` não resolverá aqui, porque o host não está usando o Numa para DNS. Limpe com `docker rm -f numa`.

### 2. Execute em primeiro plano (DNS do sistema intacto)

Instale o binário:

```bash
# macOS
brew install razvandimescu/tap/numa

# Linux
curl -fsSL https://raw.githubusercontent.com/razvandimescu/numa/main/install.sh | sh

# Arch Linux
pacman -S numa

# Windows — download from GitHub Releases
# All platforms
cargo install numa

# Nix
nix run github:razvandimescu/numa
```

```bash
sudo numa                              # Ctrl-C to stop (port 53 requires root/admin)
```

O Numa escuta na porta 53, mas seu sistema mantém o resolvedor atual até você executar `numa install`, então teste com `dig @127.0.0.1 example.com`. O dashboard fica em `http://localhost:5380`. Se a porta 53 estiver ocupada (systemd-resolved no Ubuntu/Mint), defina `bind_addr` em [`numa.toml`](https://github.com/razvandimescu/numa/blob/main/numa.toml) ou use Docker.

### 3. Definir como DNS do sistema

| Plataforma | Instalar | Desinstalar |
|----------|---------|-----------|
| macOS | `sudo numa install` | `sudo numa uninstall` |
| Linux | `sudo numa install` | `sudo numa uninstall` |
| Windows | `numa install` (admin) + reboot | `numa uninstall` (admin) + reboot |

`install` registra um serviço, aponta o DNS do sistema para o Numa e confia em sua CA local. `uninstall` reverte os três. Uma vez instalado, o dashboard também fica em **http://numa.numa**.

No macOS e Linux, o numa roda como serviço de sistema (launchd/systemd). A unit do systemd é sem privilégios (`DynamicUser=yes`, apenas `CAP_NET_BIND_SERVICE`); o daemon do launchd roda como root. `numa install` reconfigura o systemd-resolved através de um drop-in que `numa uninstall` remove; qualquer outro processo ocupando a porta 53 (dnsmasq, incluindo o do NetworkManager) precisa ser parado manualmente. No Windows, o numa inicia automaticamente no login via registro. O Windows também vincula `127.0.0.2:53` (o Dnscache embutido possui `127.0.0.1:53`) e instala uma regra NRPT para rotear consultas para lá — então edite `bind_addr`/`api_bind_addr` contra `127.0.0.2`, não `127.0.0.1`.

### Fazendo login

Via loopback (`localhost`, `127.0.0.1`, `numa.numa`) nenhum login é necessário. Qualquer outra coisa, incluindo mapeamento de porta do Docker ou o endereço LAN desta máquina, solicita o token da API, que o Numa gera na primeira inicialização. Imprima-o com `sudo numa token` (um shell de administrador no Windows) e faça login com qualquer nome de usuário. Fixe o seu próprio com `[server] api_token` ou `NUMA_API_TOKEN`.

### Removendo todo vestígio

`uninstall` restaura o DNS mas mantém o diretório de dados, então uma reinstalação mantém o mesmo token e CA. Para remover tudo, desinstale primeiro, depois exclua:

| Plataforma | Deixado para trás |
|----------|-------------|
| macOS | o binário, `/usr/local/var/numa`, `/usr/local/var/log/numa.log` |
| Linux | o binário (`/usr/local/bin/numa` do install.sh), `/var/lib/numa`, `/etc/numa` |
| Windows | o binário, `%PROGRAMDATA%\numa` |

Instalações via gerenciador de pacotes removem o binário com `brew uninstall`, `pacman -R` ou `cargo uninstall`. No Linux, `numa install` copia um binário que não consegue executar de seu local original (ex.: `~/.cargo/bin`) para `/usr/local/bin/numa`, e o uninstall deixa essa cópia.

Também exclua `~/.config/numa` se você criou uma configuração de usuário, e o caminho `[server] data_dir` se você definiu um.

## Serviços Locais

Nomeie seus serviços de desenvolvimento em vez de memorizar números de porta:

```bash
curl -X POST localhost:5380/services \
  -d '{"name":"frontend","target_port":5173}'
```

Agora `https://frontend.numa` funciona no seu navegador — cadeado verde, certificado válido, passthrough de WebSocket para HMR. Sem mkcert, sem nginx, sem `/etc/hosts`.

Adicione roteamento baseado em caminho (`app.numa/api → :5001`), compartilhe serviços entre máquinas via descoberta LAN, ou configure tudo em [`numa.toml`](https://github.com/razvandimescu/numa/blob/main/numa.toml).

## Bloqueio de Anúncios e Privacidade

Bloqueio de anúncios e rastreadores via [Hagezi Pro](https://github.com/hagezi/dns-blocklists), atualizado diariamente. Funciona em qualquer rede — cafeterias, hotéis, aeroportos. Viaja com seu laptop.

Três modos de resolução:

- **`forward`** (padrão) — proxy transparente para o DNS do sistema existente. Tudo funciona como antes, apenas com cache e bloqueio de anúncios por cima. Portais cativos, VPNs, DNS corporativo — todos respeitados.
- **`recursive`** — resolve diretamente dos servidores de nomes raiz. Sem dependência de upstream, nenhuma entidade isolada vê seu padrão completo de consultas. Adicione `[dnssec] enabled = true` para validação completa da cadeia de confiança.
- **`auto`** — sonda servidores raiz na inicialização, recursivo se alcançável, caso contrário forward sobre DoH para o Quad9 (`https://9.9.9.9/dns-query`), que então vê suas consultas. Use `forward` com seu próprio `[upstream]` para escolher um provedor diferente.

O DNSSEC valida a cadeia de confiança completa: assinaturas RRSIG, verificação DNSKEY, delegação DS, provas de negação NSEC/NSEC3. [Leia como funciona →](https://numa.rs/blog/posts/dnssec-from-scratch.html)

**Listener DNS-over-TLS** (RFC 7858) — aceita consultas criptografadas na porta 853 de clientes estritos como iOS Private DNS, systemd-resolved ou stubby. Dois modos:

- **Autoassinado** (padrão) — o numa gera uma CA local automaticamente. `numa install` a adiciona ao repositório de confiança do sistema no macOS, Linux (Debian/Ubuntu, Fedora/RHEL/SUSE, Arch) e Windows, e `numa uninstall` a remove. No iOS, instale o `.mobileconfig` de `numa setup-phone`. O Firefox mantém seu próprio repositório NSS e ignora o do sistema — confie na CA lá manualmente se precisar de HTTPS para serviços `.numa` no Firefox.
- **Traga seu próprio certificado** — aponte `[dot] cert_path` / `key_path` para um certificado publicamente confiável (ex.: Let's Encrypt via desafio DNS-01 em um domínio apontando para sua instância numa). Clientes conectam sem qualquer configuração de repositório de confiança — mesma UX do AdGuard Home ou Cloudflare `1.1.1.1`.

ALPN `"dot"` é anunciado e aplicado em ambos os modos; um handshake com ALPN incompatível é rejeitado como defesa contra confusão entre protocolos.

**Oblivious DoH** (RFC 9230) — com `[upstream] mode = "odoh"` ([receita](https://github.com/razvandimescu/numa/blob/main/recipes/odoh-upstream.md)) cada consulta é selada com HPKE para o destino e enviada através de um relay. O relay vê seu IP e o texto cifrado, o destino vê a pergunta e o IP do relay, e um relay que redireciona a consulta entrega ao novo destino algo que ele não consegue descriptografar. O Numa recusa um relay e um destino que compartilham um domínio registrável. O ODoH não oculta a conexão que você abre depois: seu ISP ainda vê o IP de destino e, sem ECH, o hostname no handshake TLS.

**Configuração do telefone** — aponte seu iPhone ou Android para o Numa em um passo:

```bash
numa setup-phone
```

Imprime um código QR. Escaneie-o, instale o perfil, ative a confiança no certificado — o DNS do seu telefone agora é roteado através do Numa sobre TLS. Requer `[mobile] enabled = true` em `numa.toml`.

## Descoberta LAN

Execute o Numa em várias máquinas. Elas se encontram automaticamente via mDNS:

```
Machine A (192.168.1.5)              Machine B (192.168.1.20)
┌──────────────────────┐             ┌──────────────────────┐
│ Numa                 │    mDNS     │ Numa                 │
│  - api (port 8000)   │◄───────────►│  - grafana (3000)    │
│  - frontend (5173)   │  discovery  │                      │
└──────────────────────┘             └──────────────────────┘
```

Da Máquina B: `curl http://api.numa` → proxiado para a porta 8000 da Máquina A. Ative com `numa lan on`.

**Modo hub**: execute uma instância com `bind_addr = "0.0.0.0:53"` e aponte o DNS de outros dispositivos para ela — eles ganham bloqueio de anúncios + resolução `.numa` sem instalar nada. `bind_addr` também aceita uma lista para vincular um subconjunto específico de interfaces. Passo a passo: [receita para toda a rede](https://github.com/razvandimescu/numa/blob/main/recipes/network-wide.md).

## Docker

```bash
# Recommended — host networking (Linux)
docker run -d --name numa --network host -v numa-data:/var/lib/numa ghcr.io/razvandimescu/numa

# Port mapping (macOS/Windows Docker Desktop)
docker run -d --name numa -p 53:53/udp -p 53:53/tcp -p 5380:5380 -v numa-data:/var/lib/numa ghcr.io/razvandimescu/numa
```

Dashboard em `http://localhost:5380`. Com mapeamento de porta ou de outro dispositivo, faça login com qualquer nome de usuário e o token de `docker exec numa numa token`. O volume `numa-data` mantém o token e a CA local entre recriações do contêiner. A imagem vincula a API e o proxy a `0.0.0.0` por padrão. Substitua com uma configuração personalizada:

```bash
docker run -d --name numa --network host -v numa-data:/var/lib/numa \
  -v /path/to/numa.toml:/root/.config/numa/numa.toml \
  ghcr.io/razvandimescu/numa
```

Multi-arquitetura: `linux/amd64` e `linux/arm64`.

Receitas compose prontas para uso:
- [`packaging/client/`](https://github.com/razvandimescu/numa/blob/main/packaging/client) — modo cliente ODoH (DNS anônimo), Numa + `numa.toml` inicial.
- [`packaging/relay/`](https://github.com/razvandimescu/numa/blob/main/packaging/relay) — relay ODoH público, Numa + Caddy + ACME.

## Como se Compara

| | Pi-hole | AdGuard Home | Unbound | Numa |
|---|---|---|---|---|
| Proxy de serviço local + TLS automático | — | — | — | domínios `.numa`, HTTPS, WebSocket |
| Descoberta de serviços LAN | — | — | — | mDNS, zero config |
| Sobrescritas de desenvolvedor (REST API) | — | — | — | Reversão automática, scriptável |
| Resolvedor recursivo | — | — | Sim | Sim, com seleção SRTT |
| Validação DNSSEC | — | — | Sim | Sim (RSA, ECDSA, Ed25519) |
| Bloqueio de anúncios | Sim | Sim | — | Hagezi Pro |
| Regras por cliente | Grupos | Sim | Views / tags | Por CIDR (`[[client_policy]]`), apenas arquivo de configuração |
| UI de administração web | Completa | Completa | — | Dashboard |
| Upstream criptografado (DoH/DoT) | Precisa de cloudflared | Apenas DoH | Apenas DoT | DoH + DoT (`tls://`) |
| Clientes criptografados (listener DoT) | Precisa de sidecar stunnel | Sim | Sim | Nativo (RFC 7858) |
| Endpoint de servidor DoH | — | Sim | — | Sim (RFC 8484) |
| Request hedging | — | — | — | Todos os protocolos (UDP, DoH, DoT) |
| Serve-stale + prefetch | — | — | Prefetch em 90% do TTL | RFC 8767, prefetch em 90% do TTL |
| Encaminhamento condicional | — | Sim | Sim | Sim (regras por sufixo) |
| Portátil (laptop) | Não (appliance) | Não (appliance) | Servidor | Binário único, macOS/Linux/Windows |
| Maturidade da comunidade | 56K stars, 10 anos | 33K stars | 20 anos | Novo |

## Executando o Numa como seu DNS Primário

**Se o Numa parar.** `numa install` registra o Numa com o launchd (macOS) ou systemd (Linux), que o reiniciam quando ele sai. Se o Numa for seu único resolvedor, as consultas DNS falham até ele reiniciar. Para parar de usar o Numa e restaurar as configurações de DNS anteriores da máquina, execute `sudo numa uninstall`.

Se o Numa estiver rodando mas os upstreams estiverem inacessíveis, ele pode servir respostas em cache por até uma hora além do TTL (RFC 8767). Nomes que ele não tenha em cache falham.

**Testes.** O parser DNS é submetido a fuzzing em cada pull request que o toca, com execuções mais longas semanalmente ([`fuzz.yml`](https://github.com/razvandimescu/numa/blob/main/.github/workflows/fuzz.yml)). O CI executa `cargo audit` nas dependências e instala, reinstala e desinstala o Numa no macOS e Linux.

**Endurecimento do resolvedor.** No modo recursivo, o Numa descarta registros de resposta fora da zona sendo consultada, recusa consultar servidores de nomes em endereços privados ou de loopback, e limita as consultas upstream e a profundidade de referral de cada lookup. Respostas sobre UDP simples devem corresponder ao ID de transação aleatório e à pergunta da consulta. Consultas ANY são recusadas. A validação DNSSEC está desativada por padrão; `numa dnssec on` a ativa. Para relatar uma vulnerabilidade de forma privada, veja [SECURITY.md](https://github.com/razvandimescu/numa/blob/main/SECURITY.md).

**O que o Numa não faz.** Sem DHCP, sem clustering, sem sincronização de configuração entre instâncias. A maioria das configurações fica em [`numa.toml`](https://github.com/razvandimescu/numa/blob/main/numa.toml), não no dashboard. Para uma rede inteira, execute-o em uma máquina que fique ligada.

## Desempenho

0.1ms para consultas em cache — iguala Unbound e AdGuard Home. O cache em nível de rede armazena bytes brutos com patch de TTL in-place. O request hedging elimina picos de p99: p99 recursivo frio 538ms vs Unbound 748ms (−28%), σ 4× mais apertado. [Benchmarks →](https://github.com/razvandimescu/numa/blob/main/benches)

## Saiba Mais

- [Blog: Numa como seu resolvedor tailnet](https://numa.rs/blog/posts/numa-tailnet-resolver.html)
- [Blog: DNS-over-TLS do Zero em Rust](https://numa.rs/blog/posts/dot-from-scratch.html)
- [Blog: Implementando DNSSEC do Zero em Rust](https://numa.rs/blog/posts/dnssec-from-scratch.html)
- [Blog: Construí um Resolvedor DNS do Zero](https://numa.rs/blog/posts/dns-from-scratch.html)
- [Referência de configuração](https://github.com/razvandimescu/numa/blob/main/numa.toml) — todas as opções documentadas inline; `numa config path` mostra qual arquivo sua instalação está usando, `numa config edit` o abre
- [REST API](https://github.com/razvandimescu/numa/blob/main/src/api.rs) — sobrescritas, cache, bloqueio, serviços, diagnósticos
- [numa-metrics](https://github.com/razvandimescu/numa-metrics) — histórico de consultas e análises duráveis, fora do host por design (sem escritas em cartão SD)

## Roadmap

- [x] Encaminhamento DNS, cache, bloqueio de anúncios, sobrescritas de desenvolvedor
- [x] Domínios locais `.numa` — TLS automático, roteamento por caminho, proxy WebSocket
- [x] Descoberta de serviços LAN — mDNS, DNS + proxy entre máquinas
- [x] DNS-over-HTTPS — upstream criptografado + endpoint de servidor (RFC 8484)
- [x] DNS-over-TLS — listener de cliente criptografado (RFC 7858) + encaminhamento upstream (`tls://`)
- [x] Oblivious DoH — modo cliente anonimizado + relay público (`numa relay`, RFC 9230)
- [x] Resolução recursiva + DNSSEC — cadeia de confiança, NSEC/NSEC3
- [x] Seleção de servidor de nomes baseada em SRTT
- [x] Failover multi-forwarder — múltiplos upstreams com ranking SRTT, pool de fallback
- [x] Request hedging — requisições paralelas resgatam perda de pacotes e latência de cauda (todos os protocolos)
- [x] Serve-stale + prefetch — RFC 8767, atualização em segundo plano em <10% do TTL e ao servir stale
- [x] Encaminhamento condicional — regras por sufixo para DNS split-horizon (Tailscale, VPNs)
- [x] Aquecimento de cache — resolução proativa para domínios configurados
- [x] Onboarding móvel — fluxo QR `setup-phone`, API móvel, perfis mobileconfig
- [ ] Integração pkarr — DNS autossoberano via Mainline DHT
- [ ] Nomes globais `.numa` — com suporte a DHT, sem registrador

## Licença

MIT