Madagascar Local Authority este o aplicație web locală, Perl-only, pentru registrul de hosturi Madagascar, manifestele DNS locale, Work Orders și autoritatea locală de certificate. Nu folosește npm, pip sau pachete CPAN instalate direct pe host.

Pentru deciziile de evoluție și schimbările de scope, vezi indexul `.doc/development-log.md` și logurile pe componente din `.doc/development-logs/`.

## Politica de dependențe

MVP-ul curent nu are dependențe CPAN instalate direct pe host. Pentru store-ul runtime folosește `DBI`/`DBD::SQLite` disponibile din distribuție sau repo-ul local auditat, plus SQLite.

`var/host-manager.sqlite` este sursa de adevăr runtime pentru hosturi, aliasuri, vhosturi, taguri, Work Orders, workeri de date și certificate emise. `hosts.yaml` este produsul finit exportat din baza runtime și seed pentru baze noi. La prima pornire, aplicația seed-uiește tabelele din `config/hosts.yaml` și `config/work-orders.yaml` dacă baza nu are încă rânduri operaționale. Aplicația este complet în spatele autentificării OTP pentru orice date de registru, exporturi sau modificări.

Git rămâne mecanismul pentru cod, seed-uri, exporturi și istoric manual. Aplicația nu mai scrie registry-ul live direct în working tree, ca editările făcute în UI să nu se piardă la push/deploy de cod.

Schimbările cu impact operațional care elimină nume sau schimbă semantica serviciilor locale se fac prin Work Order (WO), nu prin ștergere directă din UI. WO-ul rămâne în store-ul runtime, exprimă intenția operațională și trebuie dus până la capăt înainte să modifice registrul.

Endpoint-uri publice:

- `/` — pagina de login/aplicație, fără date de host până la autentificare

- `POST /api/collect/dhcp-leases` — ingest DHCP lease push, protejat cu `HOST_MANAGER_DHCP_PUSH_TOKEN`

- `/api/hosts`

- `/api/tags`

- `/api/work-orders`

- `/api/exports/hosts.yaml`

- `/api/ca/status`

- `/download/hosts.yaml`

- `/download/ca.crt`

- `POST /api/hosts/upsert`

- `POST /api/tags/upsert`

- `POST /api/work-orders/checklist`

- `POST /api/work-orders/confirm`

Checkout-ul de dezvoltare este local:

Repo-ul canonic în GitPrep este:

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

https://hosts.madagascar.xdev.ro/

```

ssh jumper.madagascar.xdev.ro 'cat /etc/xdev/host-manager.totp-uri'

```

Codul aplicației se modifică local și se publică pe jumper cu:

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

1. Hosturile se editează în aplicație; store-ul runtime este `var/host-manager.sqlite`.

2. Operatorii autentificați pot descărca `/download/hosts.yaml` sau `/download/monitoring.json`; UI-ul afișează și raw `hosts.yaml`.

## Work Orders

Work Orders sunt păstrate în SQLite. `config/work-orders.yaml` rămâne seed/snapshot compatibil pentru instalări noi și export manual.

- este blocată dacă există pași de checklist nemarcați `done`

- elimină numele declarate din registry-ul SQLite

- marchează WO-ul ca `confirmed`

- pune în coadă sincronizarea resolverelor locale prin `host-manager-dns-publish.path`

După confirmare, operatorul poate verifica manual resolverele cu:

dig @192.168.2.100 nume.madagascar.xdev.ro +short

```

Primul WO curent este pentru retragerea numelor locale `pmx.*`/`pbs.*` create istoric pentru vhosturi nginx cu certificate Let's Encrypt. Odată cu CA-ul local, aceste nume nu mai trebuie să existe ca vhosturi separate pentru interfețele Proxmox/PBS, dar rămân publicate până când checklist-ul operațional este complet și WO-ul este confirmat.

## Convenții de nume

`madagascar.xdev.ro` este domeniul implicit al rețelei interne. Hosturile sunt identificate în baza de date prin FQDN complet, iar UI-ul păstrează temporar `id` ca identificator compatibil.

Modelul curent de adresare păstrează un singur IP canonic per host. UI-ul și API-ul expun acest câmp ca `ip`, iar store-ul runtime îl mapează în coloanele istorice SQLite doar pentru compatibilitate internă.

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

Aliasurile derivate nu se declară separat în `hosts.yaml` și nu sunt afișate ca zgomot separat în UI. Ele sunt păstrate în tabelul `host_aliases` și pot apărea în exporturile tehnice care au nevoie de nume efective.

## Git și managementul cheilor

Varianta obligatorie pentru servicii automate este să consume exporturi generate și verificate, nu să depindă de HTTP neautentificat. Serviciile care sincronizează DNS, monitorizare sau inventare primesc chei dedicate, cu acces minim.

  var/host-manager.sqlite  sursă runtime relațională pentru registry și Work Orders

  host-manager             editează SQLite cu OTP

  sync_local_hosts.sh      aplică DNS după review/verificare

  export verificat         citesc hosts.yaml/monitoring.json

```

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

## Autoritate locală de certificate

Madagascar Local Authority include un helper OpenSSL pentru o autoritate locală de certificate pentru hosturi. Cheia privată CA nu este în git și nu este servită prin aplicație.

- Se semnează preferabil CSR-uri generate pe hosturi; cheia privată a hostului nu trebuie copiată în Madagascar Local Authority.

- CA private key rămâne local pe jumper și în afara git-ului.

## Limitări MVP

- Conflict engine-ul verifică doar consistența locală din registry-ul SQLite.

- DHCP și mDNS sunt inputuri observate pentru hinturi/autocomplete, nu surse de adevăr pentru registry.