licence-server/docs/asp-terminia/02-api-ugovor-firmware.md

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?)	✅ nema je — vidi ispod
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.	✅ radi kako treba — vidi ispod
P3	Tačan skup polja license objekta za ASP proizvod (limits/features imena)	✅ odgovoreno uz Z1 (2026-07-25) — vidi ispod
P4	expires_at format (ISO8601?) — firmware poredi prvih 10 znakova (YYYY-MM-DD)	✅ RFC3339 — vidi ispod

Odgovori P1, P2, P4 (2026-07-25, čitanjem Go koda)

P1 — formule NEMA. Server ne računa fingerprint. internal/service/activation_service.go prima req.MachineFingerprint i poredi ga kao običan string (existing.MachineFingerprint == req.MachineFingerprint). Znači: šta god firmware pošalje, to je fingerprint — samo mora biti dosledno isto pri svakoj aktivaciji istog uređaja. Postojeći FW oblik sha256:<hex od "AA:BB:CC:DD:EE:FF"> radi bez ijedne izmene na obe strane. Posledica: nema FW izmene za P1 — pitanje je bilo bespredmetno.

P2 — isti uređaj SME ponovo. Radi kako teren traži. Ako postoji aktivna aktivacija sa istim fingerprintom → server osveži last_seen i ponovo vrati potpisanu licencu. Dakle re-aktivacija posle brisanja NVS-a / fabričkog reseta na ISTOM uređaju prolazi. Sa drugim fingerprintom → ALREADY_ACTIVATED uz podatke gde je već aktivirana. Ponašanje je tačno ono što nam treba, ništa se ne menja.

P4 — expires_at je RFC3339 (2027-01-01T00:00:00Z), prazan string kad je licenca trajna. Počinje sa YYYY-MM-DD, pa poređenje prvih 10 znakova u firmveru radi. Trajna licenca = prazno polje — proveriti da FW to tumači kao „bez roka", a ne kao istekla (vidi Z2 korak 4).

Nalaz uz P3 — potpis je stabilan (provereno)

Bila je opravdana sumnja: server potpiše licenseJSON, pa ga ponovo serijalizuje u odgovor (json.Unmarshal → ActivateResponse). Da se bajtovi razlikuju, potpis ne bi važio na uređaju. Ne razlikuju se: oba puta se marshal-uje isti tip model.LicenseData, a Go encoding/json je determinističan (polja u redosledu deklaracije, isto escape-ovanje); limits/features su json.RawMessage pa prolaze doslovno (kompaktirani isto oba puta). Potpis će se poklopiti.

DVA NESLAGANJA POLJA (ne blokiraju aktivaciju, kvare samo prikaz)

Firmware (licenca.cpp) čita edition i customer, a server ih ne šalje u tom obliku:

FW traži	Server šalje	Posledica
edition (string)	nema ga (ima license_type)	polje ostaje prazno u UI
customer (string)	customer je objekat {"name","email"}	pure::jsonStr traži " a nailazi na { → vrati false, polje prazno
customer_name (rezerva)	nema ga	rezerva ne pomaže

Aktivacija, potpis, fingerprint i rok rade normalno — samo „Izdanje" i „Korisnik" u SPA ostaju prazni. Popravka je jednostavna, ali je odluka gde: ili FW da čita license_type i customer.name (jedna-dve linije), ili server da doda edition/customer_name u LicenseData. Preporuka: menjati FW, jer server već opslužuje žive klijente (ESIR/ARV/LIGHT_TICKET) i njegov odgovor se ne dira bez potrebe.

Odgovor P3 (2026-07-25)

Server čuva limits/features kao json.RawMessage — ne tumači ih, samo ih potpisano vraća (potvrđeno čitanjem internal/model/license.go, internal/model/request.go). Firmware (ASP-TERMINIA repo, licenca.cpp) trenutno uopšte ne čita ova dva polja — parsira samo edition, customer/customer_name, expires_at, grace_days, machine_fingerprint. Enforcement (kad features/limits postanu bitni) je odložen na Z4.

Zaključak: format nije bio ni bitan za Z1/Z2 (bez FW koda koji ga čita, ništa se ne lomi bilo kojim izborom). Proizvod ASP-TERMINIA je zaveden (migrations/004_seed_asp_terminia.sql) sa placeholder vrednostima:

"limits":   {"max_readers": 4, "max_cards": 5000}
"features": ["FEAT_CARDCHECK", "FEAT_ISSUE", "FEAT_PRINT", "FEAT_CATALOG", "FEAT_ANTIPASS", "FEAT_SYNC", "FEAT_OTA"]

features su imena iz ASP repo docs/18-licenciranje-po-mac.md §6.3 (string nizovi, ne bitmaska — server ionako ne tumači, a string nizovi su čitljiviji u dashboardu i lakši za FW proveru kad enforcement dođe: "FEAT_X" in niz umesto bitmaske). Ovo NIJE konačna odluka o paketima (basic/pro) — vlasnik to još nije odlučio; svaka izdata licenca nosi svoje limits/features nezavisno od default-a proizvoda, pa se default sme promeniti kasnije bez posledica po već izdate licence.