Nenad Djukic 47721f400d Z1: upisan odgovor na P3 (limits/features format) u API ugovor

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

2026-07-25 08:41:23 +02:00

4.3 KiB

Raw Blame History

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)	✅ odgovoreno uz Z1 (2026-07-25) — vidi ispod
P4	`expires_at` format (ISO8601?) — firmware poredi prvih 10 znakova (`YYYY-MM-DD`)	⬜ potvrditi

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.

4.3 KiB Raw Blame History