# API ugovor koji FIRMWARE očekuje (merodavno za server stranu)

> Ovo je ugovor kakav je VEĆ implementiran u firmveru (0.10.0+). Server strana se
> usklađuje sa OVIM (ili se promena dogovara pa se menja i firmware — nikad tiho).

## 1. Aktivacija

```
POST {licUrl}/activate
Content-Type: application/json

{
  "license_key":         "ASP-XXXX-XXXX-XXXX",
  "machine_fingerprint": "sha256:<sha256hex od 'AA:BB:CC:DD:EE:FF'>",
  "app_version":         "0.11.0",
  "os":                  "esp32s3",
  "hostname":            "TERM-001"
}
```

Očekivan odgovor `200`:

```
{
  "license": {
    ... polja licence, među njima:
    "machine_fingerprint": "sha256:...",   ← ako postoji, MORA biti otisak uređaja
    "expires_at": "2027-01-01T00:00:00Z",  ← ili prazno/odsutno = trajna
    "grace_days": 14,
    "edition": "...", "customer": "...", "license_id": "..."
  },
  "signature": "RSA-SHA256:<base64 potpisa nad SIROVIM bajtovima license objekta>"
}
```

**Kritično:** potpis se računa nad TAČNIM bajtovima `license` objekta onako kako su
poslati u HTTP telu (od `{` do para `}`). Firmware iseca taj isečak iz sirovog tela
(string-safe brojanje zagrada) i verifikuje. **Nikakvo „lepše" formatiranje odgovora
naknadno** — menja bajtove → lomi potpis.

## 2. Provera

```
POST {licUrl}/validate
{ "license_key": "...", "machine_fingerprint": "sha256:..." }
```

Očekivano: `{"valid": true/false, "expires_at": "...", "revoked": true/false}`.
Firmware tumači: `revoked` → poruka „licenca OPOZVANA na serveru"; `!valid` →
„server kaže da licenca ne važi". Mrežna/HTTP greška NE dira lokalno stanje.

## 3. Greške

HTTP ≠ 200 → firmware čita JSON polje `"error"` i prikazuje ga korisniku uz HTTP kod
(npr. `HTTP 403 (KEY_REVOKED)`). Poželjno je da server uvek vraća `{"error":"KOD"}`.

## 4. Ponašanje klijenta koje server sme da računa

- Klijent NIKAD ne šalje privatne podatke — samo gore navedena polja.
- Klijent poštuje odgovor samo ako je potpis valjan; HTTP 200 bez valjanog potpisa
  se odbacuje (zaštita i od MITM na self-signed kanalu).
- Nakon uspešne aktivacije klijent NE zove server pri svakom startu — offline
  verifikacija iz NVS. `validate` se zove ručno iz UI (kasnije: periodično uz sync).

## 5. Otvorena pitanja za usklađivanje (uneti odgovore ovde)

| # | Pitanje | Status |
|---|---|---|
| P1 | Tačna formula `machine_fingerprint` u Go kodu (ulazni string, velika/mala slova, dvotačke?) | ⬜ proveriti u kodu servera |
| P2 | Da li `activate` na VEĆ aktiviran ključ + ISTI fingerprint vraća licencu ponovo (re-aktivacija posle brisanja NVS) ili `ALREADY_ACTIVATED`? Za teren nam treba: isti uređaj sme ponovo. | ⬜ proveriti/podesiti |
| P3 | Tačan skup polja `license` objekta za ASP proizvod (limits/features imena) | ⬜ definisati uz Z1 |
| P4 | `expires_at` format (ISO8601?) — firmware poredi prvih 10 znakova (`YYYY-MM-DD`) | ⬜ potvrditi |