# Madagascar Local Authority MVP

Numele de produs este `Madagascar Local Authority`. Numele tehnic al serviciului, userului Unix, path-ului și fișierelor de environment rămâne `host-manager`.

## 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:

- `/api/ca/certificates`

- `/download/local-hosts.tsv`

- `/download/monitoring.json`

- `POST /api/hosts/delete`

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

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

```bash

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

```

Un WO nu înseamnă că numele nu mai este în uz. Înseamnă doar că vrem să ajungem acolo. Pentru retragerea unui nume, checklist-ul trebuie să acopere pașii reali: ștergerea vhostului, înlocuirea certificatelor publice cu certificate locale, reîncărcarea serviciilor, testarea accesului și verificarea că nu mai există consumatori.

În MVP, acțiunea suportată este:

```text

remove_name(host_id, name)

```

Confirmarea unui WO:

- cere tastarea exactă a ID-ului WO în interfață

- marchează WO-ul ca `confirmed`

- regenerează `config/local-hosts.tsv`

- nu rulează automat sync-ul către resolvere

După confirmare, operatorul verifică schimbarea în git și rulează explicit:

```bash

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

```

`madagascar.xdev.ro` este domeniul implicit al rețelei interne. În `config/hosts.yaml` se declară doar numele canonice/FQDN-urile necesare.

Pentru orice nume `*.madagascar.xdev.ro`, aplicația derivă automat aliasul scurt prin eliminarea sufixului `.madagascar.xdev.ro`.

Exemple:

- `autonas01.madagascar.xdev.ro` produce automat aliasul `autonas01`

- `pmx.baobab.madagascar.xdev.ro` produce automat aliasul `pmx.baobab`

Aliasurile derivate nu se declară separat în `hosts.yaml`. Ele apar în API, monitoring export și `local-hosts.tsv` ca nume efective.

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.

Locația implicită:

```text

/usr/local/xdev-host-manager/var/ca

```

Inițializare CA, pe jumper:

```bash

cd /usr/local/xdev-host-manager

sudo scripts/ca_manager.sh init

```

Semnare CSR pentru un host:

```bash

sudo scripts/ca_manager.sh sign-csr host-id /path/to/host.csr host.madagascar.xdev.ro host

```

Aplicația web, după OTP, poate afișa statusul CA, lista certificatelor emise și poate descărca certificatul public CA prin `/download/ca.crt`.

Reguli:

- Endpoint-urile CA sunt în spatele OTP-ului.

- Automatizarea pentru emitere direct din UI se adaugă ulterior doar cu helper privilegiat și audit separat.

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