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

```text

/Users/bogdan/Documents/Workspaces/Xdev/Madagascar/LocalAuthority

```

Instanța runtime 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

```bash

scripts/deploy_to_jumper.sh

```

Scriptul de deploy nu copiază implicit `config/`, deoarece acesta conține date operaționale editabile de aplicația live. Folosește `--include-config` doar când vrei explicit să înlocuiești registrul runtime.

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.