# Host Manager MVP

Host Manager este o aplicație web locală, Perl-only, pentru registrul de hosturi Madagascar. Nu folosește npm, pip sau pachete CPAN instalate direct pe host.

## Politica de dependențe

Perl-ul livrat de distribuție este acceptat ca bază de runtime. Modulele Perl incluse în distribuție sau în core pot fi folosite direct.

Pachetele CPAN nu se instalează direct pe host cu `cpan`, `cpanm` sau mecanisme similare. Dacă aplicația are nevoie de un modul CPAN, modulul trebuie făcut disponibil prin repo-ul local după audit. Este acceptabilă o versiune mai veche/stabilă din repo-ul local; nu urmărim neapărat ultima versiune upstream.

MVP-ul curent nu are dependențe CPAN externe.

## Rol

`config/hosts.yaml` este registrul editabil și trebuie menținut în git. Aplicația este complet în spatele autentificării OTP pentru orice date de registru, exporturi sau modificări.

Git rămâne mecanismul de audit, istoric și rollback. Aplicația nu înlocuiește repo-ul și nu devine o bază de date separată.

Endpoint-uri publice:

- `/` — pagina de login/aplicație, fără date de host până la autentificare
- `/api/session` — status boolean al sesiunii
- `/api/login`
- `/api/logout`
- `/healthz` — healthcheck minimal, fără path-uri sau date interne

Endpoint-uri cu OTP:

- `/api/hosts`
- `/download/hosts.yaml`
- `/download/local-hosts.tsv`
- `/download/monitoring.json`
- `POST /api/hosts/upsert`
- `POST /api/hosts/delete`
- `POST /api/render/local-hosts-tsv`

## Pornire locală

```bash
HOST_MANAGER_TOTP_SECRET="BASE32_SECRET_AICI" \
perl scripts/host_manager.pl --bind 127.0.0.1 --port 8088
```

Deschide:

```text
http://127.0.0.1:8088/
```

Implicit serverul ascultă doar pe loopback. Pe jumper, publicarea se face prin nginx, ca vhost separat, cu proxy către `127.0.0.1:8088`.

Vhost-ul implicit propus este:

```text
hosts.madagascar.xdev.ro
```

Configurațiile de deployment sunt în `deploy/jumper/`.

Instanța de pe jumper este instalată în `/usr/local/xdev-host-manager` și publicată prin:

```text
http://hosts.madagascar.xdev.ro/
```

Secretul TOTP nu este în repo. Pentru bootstrap, citește URI-ul root-only de pe jumper:

```bash
ssh is-vpn-gw 'cat /etc/xdev/host-manager.totp-uri'
```

## OTP

`HOST_MANAGER_TOTP_SECRET` trebuie să fie un secret Base32 compatibil TOTP. Fără această variabilă, healthcheck-ul și pagina de login funcționează, dar login-ul, API-ul, download-urile și scrierile nu.

Secretul nu se comite în repo. Dacă avem nevoie de integrare cu un manager de secrete sau systemd environment file, se definește separat pe host.

## Flux

1. Hosturile se editează în aplicație sau direct în `config/hosts.yaml`.
2. Operatorii autentificați pot descărca `/download/hosts.yaml`, `/download/local-hosts.tsv` sau `/download/monitoring.json`.
3. Pentru DNS local, butonul `Write local-hosts.tsv` regenerează `config/local-hosts.tsv`.
4. Sincronizarea efectivă către is-vpn-gw și as01 rămâne:

```bash
./scripts/sync_local_hosts.sh --apply --verify
```

## Git și managementul cheilor

Varianta obligatorie pentru servicii automate este să citească `config/hosts.yaml` din git, nu să depindă de HTTP neautentificat. Serviciile care sincronizează DNS, monitorizare sau inventare primesc chei dedicate, cu acces minim.

Reguli:

- Fiecare host/serviciu automat are propria cheie SSH, fără reutilizare între roluri.
- Cheile de consum sunt read-only pentru repo.
- Cheile care pot scrie în repo sunt rare, separate și folosite doar de componenta de management.
- Cheile nu se comit în repo și nu se pun în `hosts.yaml`.
- Pentru deployment pe hosturi, se preferă chei restrânse la comanda necesară sau deploy keys read-only unde platforma git permite.
- Pull-ul automat trebuie să valideze fișierele înainte de aplicare; de exemplu `perl -c scripts/host_manager.pl` și `./scripts/sync_local_hosts.sh --verify` după generarea DNS.

Modelul recomandat:

```text
git repo
  config/hosts.yaml        sursă versionată
  config/local-hosts.tsv   manifest generat/versionat pentru DNS local

jumper
  host-manager             editează working tree cu OTP
  sync_local_hosts.sh      aplică DNS după review/verificare

servicii consumatoare
  git pull read-only       citesc hosts.yaml/local-hosts.tsv
```

Pentru etapa MVP, aplicația nu face commit/push automat. După o modificare, schimbarea rămâne vizibilă în working tree și se comite explicit după review. Automatizarea commit/push poate fi adăugată ulterior, dar numai cu cheie separată și reguli clare de semnare/audit.

## Limitări MVP

- Parserul YAML acceptă schema strictă generată de aplicație, nu YAML arbitrar.
- Conflict engine-ul verifică doar consistența locală din `hosts.yaml`.
- DHCP, mDNS, `hosts-local.yaml` și `madagascar.json` sunt încă surse pentru audit manual sau pentru următorul collector.