3d7b12db70
P1 - formule NEMA: server ne racuna fingerprint, poredi ga kao obican
string. Postojeci FW oblik sha256:<hex MAC-a> radi bez izmene na obe
strane. Pitanje je bilo bespredmetno.
P2 - isti uredjaj SME ponovo: isti fingerprint -> osvezi last_seen i
ponovo vrati potpisanu licencu (re-aktivacija posle brisanja NVS/fabrickog
reseta prolazi). Drugi fingerprint -> ALREADY_ACTIVATED. Tacno ono sto
teren trazi, nista se ne menja.
P4 - expires_at je RFC3339; trajna licenca = prazan string. Poredjenje
prvih 10 znakova u FW radi.
NALAZ 1 (provera sumnje): potpis JE stabilan. Server potpise licenseJSON pa
ga PONOVO serijalizuje u odgovor - da se bajtovi razlikuju, potpis ne bi
vazio na uredjaju. Ne razlikuju se: oba puta isti tip model.LicenseData,
Go encoding/json je determinististican, limits/features su json.RawMessage
pa prolaze doslovno.
NALAZ 2 (ne blokira, kvari prikaz): FW cita 'edition' i 'customer' kao
stringove, a server nema 'edition' (ima license_type) i salje 'customer'
kao OBJEKAT {name,email}. pure::jsonStr naidje na '{' umesto '"' i vrati
false -> oba polja ostanu prazna u SPA. Aktivacija/potpis/rok rade normalno.
Preporuka: menjati FW (citati license_type i customer.name), ne server -
server vec opsluzuje zive klijente ESIR/ARV/LIGHT_TICKET.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
150 lines
7.0 KiB
Markdown
150 lines
7.0 KiB
Markdown
# 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:
|
|
|
|
```json
|
|
"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.
|