# Raport weryfikacji jakości specyfikacji — Browser-VPN

**Dokument:** `2026-07-22-browser-vpn-product-design.md` (738 linii) · **Data:** 2026-07-22
**Zakres:** kompletność, jednoznaczność, spójność, mierzalność, realność

## 1. Podsumowanie

Specyfikacja jest dojrzała jak na draft: opisuje pełny przepływ zakupu i sesji, stack, model danych, API, monitoring i deployment, uczciwie wskazując ograniczenia i pytania otwarte. Główne ryzyka to niejednoznaczność naliczania czasu i wiązania urządzenia oraz napięcie między deklaracją prywatności a modelem uprawnień kontenerów. Przed implementacją trzeba domknąć trzy problemy krytyczne.

## 2. Ocena ogólna: **6.5 / 10**

Kompletność 6 · Jednoznaczność 5 · Spójność 7 · Mierzalność 6 · Realność 7.

## 3. Znalezione problemy

### Krytyczne

**K1 — Sprzeczna semantyka naliczania czasu (§1.3 pkt 10)**
> „Time starts counting from first access, with a 1-hour buffer after container launch."
Nie wiadomo, czy zegar rusza od pierwszego dostępu, czy od startu kontenera + 1h. Kontener (koszt) działa, zanim opłacony zegar wystartuje. Wymaga jednej reguły.

**K2 — Podwójne przechowywanie `deviceToken` (§1.3 pkt 8, §10.2)**
> „stored in httpOnly cookie and localStorage."
Cookie httpOnly jest niedostępne z JS, localStorage nie leci w żądaniach — źródła mogą się rozjechać. Dla audytorium „total privacy" (incognito, czyszczenie storage) wiązanie zrywa się, a brak recovery: „No token → redirect to error page". Wskaż jedno źródło prawdy + flow odzyskania.

**K3 — `SYS_ADMIN` kontra izolacja (§10.1)**
> „Only required capabilities are granted (`NET_ADMIN`, `SYS_ADMIN`...)."
`SYS_ADMIN` jest bliskie rootowi i podważa tezę o silnej izolacji. Dla produktu privacy-first udokumentuj mitygacje (seccomp/AppArmor, user namespaces, rootless) lub uzasadnij konieczność.

### Ważne
- **W1 (§9.3, §10.2):** `sessionId`/`ord-` w URL jako jedyny sekret trafia do historii/logów/Referer; brak zdefiniowanej entropii formatu `ord-XXXXXX-XXXXXX` = ryzyko zgadnięcia.
- **W2 (§10.3 vs §14.2):** „No personal data stored" vs „Operational logs" — zakres logów nieokreślony, napięcie z obietnicą prywatności.
- **W3 (§7.2):** endpointy bez schematów request/response i kodów błędów — blokuje testy akceptacyjne.
- **W4 (§3.2):** „active containers < 50" bez limitów RAM/CPU na kontener i specyfikacji serwera — limit nieweryfikowalny.
- **W5 (§10.4):** „Optional TOTP", „Recommended: restrict by IP" — dla panelu produkcyjnego 2FA i allowlista powinny być wymagane.

### Kosmetyczne
- **C1 (§1.3):** „full country list like Mullvad/ProtonVPN" — ~40 vs ~70 krajów, różny koszt; niemierzalne.
- **C2 (§10.6):** „weekly or on upstream release" — brak priorytetu przy kolizji.

## 4. Brakujące elementy

Rate limiting (brak zupełny) · cele SLA/uptime (single server = SPOF) · strategia testów · format i kody błędów API · ścieżka „opłacone, kontener nie wstał" mimo „No refunds" (§4.4) · trwałość kolejki/sesji przy awarii PostgreSQL · warstwa prawna (ToS, jurysdykcja, żądania organów).

## 5. Mocne strony

Jawny zakres wyłączony (§1.4) ogranicza scope creep · priorytetyzacja MoSCoW (§13) · konkretne, mierzalne progi alertów (§11.3) · tabela ryzyk z mitygacjami i uczciwe ograniczenia (§14) · dopracowany model danych z regułami kodów rabatowych (§6.4) · kompletna procedura backup/restore i migracji (§11.5, §12.5) · sekcja pytań otwartych (§15).

## 6. Rekomendacje

1. Domknąć K1–K3 przed implementacją: jednoznaczna reguła zegara, jedno źródło `deviceToken` + recovery, uzasadnienie/mitygacja `SYS_ADMIN`.
2. Wymusić TOTP + allowlistę IP dla `/admin/*`; określić entropię `ord-`/`ses-` (min. 128 bit).
3. Dopisać kontrakty API (schematy, kody błędów) — baza pod testy.
4. Zbenchmarkować 1 kontener i z tego wyprowadzić limit instancji oraz minimalną specyfikację serwera.
5. Doprecyzować politykę logów (§10.3/§14.2) i ścieżkę „opłacone, brak usługi"; uzupełnić rate limiting, SLA i strategię testów.

---
*Werdykt: gotowa do fazy planowania po usunięciu trzech niejednoznaczności krytycznych. Status „Draft — pending review" jest adekwatny.*