# 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

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ă.

- `/api/session` — status boolean al sesiunii

- `/api/login`

- `/api/logout`

Healthcheck-ul `/healthz` este disponibil doar pe backend-ul local (`127.0.0.1:8088`). Vhost-ul nginx nu îl expune.

Endpoint-uri cu OTP:

- `/download/hosts.yaml`

- `/download/local-hosts.tsv`

- `/download/monitoring.json`

- `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

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`.

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

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

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.