# 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 îl expune read-only pentru servicii și, cu autentificare OTP, permite modificări controlate în working tree.

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 read-only:

- `/download/hosts.yaml` — registrul complet
- `/download/local-hosts.tsv` — manifest DNS local derivat
- `/download/monitoring.json` — listă pentru monitorizare
- `/api/hosts` — JSON cu hosturi și probleme detectate

Endpoint-uri cu OTP:

- `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ă, download-urile read-only funcționează, dar login-ul ș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. Serviciile externe descarcă `/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 preferată pentru servicii automate este să citească `config/hosts.yaml` din git, nu să depindă direct de sesiunea web. 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/monitoring.json/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.