Raport weryfikacji jakości specyfikacji — Browser-VPN

Data weryfikacji: 2026-07-22

Dokument: /root/browser-vpn-deploy/docs/superpowers/specs/2026-07-22-browser-vpn-product-design.md (738 linii)

Publikacja: https://10s.pl/v2-private-browser

1. Podsumowanie

Specyfikacja Browser-VPN to dobrze ustrukturyzowany dokument (738 linii, 15 sekcji), który pokazuje przemyślany produkt i samoświadomość autora co do ograniczeń. Niestety zawiera jeden krytyczny błąd architektoniczny — opisany mechanizm proxy z Caddy nie istnieje w standardowej wersji tego narzędzia — oraz kilka istotnych luk (koszty serwera, brak timeoutu płatności, brak recovery device binding). Jest to solidny draft, ale wymaga poprawek przed rozpoczęciem implementacji.

2. Ocena ogólna: 6/10

Dobry pierwszy draft z przemyślanym modelem danych i przepływami, ale z blokującym błędem architektonicznym, który wymaga przeprojektowania Caddy'ego lub zmiany reverse proxy.

3. Znalezione problemy

Krytyczne (blokują implementację)

KRYTYCZNY #1 — Caddy nie obsługuje dynamicznego proxy opisanego w sekcji 9.3

Sekcja 9.3 opisuje przepływ: Caddy pyta backend GET /api/sessions/:id/resolve, backend zwraca localhost:port, a Caddy proxy ruch do tego portu. To nie jest funkcjonalność standardowego Caddy'ego — wymagałoby to napisania własnego modułu w Go, użycia Caddy API z zewnętrznym skryptem, albo zmiany reverse proxy na Traefik (który ma Docker provider i dynamiczny routing) lub Nginx z własnym skryptem konfiguracji. Fundament architektury jest niezgodny z możliwościami deklarowanego narzędzia.

KRYTYCZNY #2 — Brak oszacowania kosztów i wymagań sprzętowych serwera

Sekcja 3.2 ustala limit 50 aktywnych kontenerów. Każdy kontener z przeglądarką (Chrome/Brave/Firefox na LSIO + WireGuard + noVNC/selkies) zużywa 1-2 GB RAM. 50 kontenerów = 50-100 GB RAM. Pojedynczy serwer z 64-128 GB RAM na renomowanym providerze (Hetzner, OVH, Netcup) to koszt $200-600/miesiąc. Bez tego wyliczenia nie można ocenić realności biznesowej — ceny ($5/dzień, $15/tydzień) przy pełnym obciążeniu dają przychód $250-750/miesiąc, co ledwo pokrywa koszty serwera.

Ważne (istotne ryzyko)

WAŻNY #3 — Brak timeoutu dla płatności pending

Sekcja 6.1 definiuje statusy: pending, paid, queued, active, expired, cancelled, ale nie ma mechanizmu timeoutu. Zamówienie w statusie pending może wisieć w nieskończoność, jeśli użytkownik rozpocznie płatność i nie dokończy. Sekcja 4.4 mówi o "auto-expire po konfigurowalnym timeoutcie", ale nie jest to zaimplementowane w modelu danych ani w schedulerze.

WAŻNY #4 — Device binding bez mechanizmu recovery

Sekcja 1.3 pkt 7-9 i 10.2: magic link działa tylko z pierwszego urządzenia, deviceToken w httpOnly cookie + localStorage. Jeśli użytkownik wyczyści ciasteczka, zmieni przeglądarkę lub urządzenie — traci dostęp do wykupionej sesji bez możliwości odzyskania. Autor jest tego świadomy (Sekcja 14.2: "No recovery — by design for anonymity"), ale w praktyce oznacza to duże ryzyko supportu i utraty klienta.

WAŻNY #5 — Admin panel niedospecyfikowany

Sekcja 10.4: "Password-protected, optional TOTP." Brak definicji: jakie akcje admin może wykonać? Czy może stopować kontenery, anulować zamówienia, blokować regiony? Brak endpointów i uprawnień.

WAŻNY #6 — Niejednoznaczność "1-hour buffer"

Sekcja 1.3 pkt 10: "Time starts counting from first access, with a 1-hour buffer after container launch." Czy to 1 godzina na pierwsze logowanie? Czy darmowy czas przed naliczeniem? Czy bufor na opóźnienia? Nieprecyzyjne, co prowadzi do różnych implementacji.

WAŻNY #7 — Brak kryteriów akceptacji dla żadnego przepływu

Żaden z 15 przepływów (zakup, aktywacja, sesja, wygaśnięcie, support, backup) nie ma zdefiniowanych warunków akceptacji. Dla produktu płatnego to ryzyko — nie wiadomo, kiedy test uznać za przechodzący, a implementację za skończoną.

Kosmetyczne (drobne poprawki)

KOSMETYCZNY #8 — Statusy orders nie uwzględniają underpaid

Sekcja 6.1: statusy pending, paid, queued, active, expired, cancelled. Brak statusu underpaid — Trocador może zwrócić płatność o niższej wartości niż oczekiwano (opłaty sieciowe, kurs). Obecnie system nie ma jak obsłużyć tej sytuacji.

KOSMETYCZNY #9 — Brak diagramu ERD

Sekcja 6 opisuje 7 tabel z kolumnami, ale nie ma wizualnych relacji ani kluczy obcych (poza order_id w sessions i tickets). Dla implementacji bazy danych przydałby się diagram ERD.

KOSMETYCZNY #10 — Niejasne jednostki w alertach CPU/RAM

Sekcja 11.3: "CPU > 80% or RAM > 80%". Procent czego? Całkowitej pojemności serwera? Jednego rdzenia? Średnia z ostatnich X minut? Warto doprecyzować okno pomiarowe.

4. Brakujące elementy

• Diagram ERD z relacjami
• Kryteria akceptacji — dla każdego z 15 przepływów
• Koszty serwera i marża — 50 kontenerów × RAM, CPU, pasmo → koszt miesięczny vs przychód
• Timeout płatności — brak mechanizmu czyszczenia porzuconych zamówień
• Mechanizm recovery device binding — PIN, challenge przez order number
• Definicja admin panelu — jakie akcje, jakie uprawnienia, jaki auth
• Obsługa underpaid — co się dzieje, gdy wpłynie mniej niż oczekiwano
• Testy i QA — brak sekcji o testach (unit, integration, e2e, smoke)
• Rate limiting — brak ochrony endpointów przed DDoS/abuse

5. Mocne strony

• Bardzo szczegółowy model danych — 7 tabel z kolumnami, typami, notatkami. Solidna podstawa do implementacji bazy danych.
• Przemyślany flow zakupu i sesji — mapa stanów (pending → paid → queued → active → expired) pokazuje dojrzałe myślenie o cyklu życia zamówienia.
• Świadomość ograniczeń — Sekcja 14 ("Conscious Limitations and Risks") pokazuje, że autor zna trade-offy: single server, crypto-only, no refunds, brak user accounts.
• Dobry monitoring i alerty — Sekcja 11 zawiera konkretne interwały (30s, 1m, 5m, 1h), progi (80% CPU/RAM, 50 kontenerów), i kanał alertów (Telegram).
• Otwarte pytania — Sekcja 15 to 5 konkretnych, nierozstrzygniętych kwestii. Dowód, że autor nie udaje, że wszystko wie.
• Bezpieczeństwo adresowane wprost — izolacja kontenerów, brak danych osobowych, webhook validation, automatyczne czyszczenie historii.
• MVP priorytetyzacja — Sekcja 13 dzieli funkcje na Must Have (14 pozycji), Should Have (4), Could Have (5).

6. Rekomendacje

1. PRZEPROJEKTUJ Caddy'ego — Opisany mechanizm proxy nie działa. Opcje: (a) użyj Traefik z Docker providerem — automatycznie wykrywa kontenery i routuje na podstawie etykiet Docker, (b) napisz prosty moduł Caddy w Go, (c) użyj Nginx z własnym skryptem aktualizującym konfigurację. Rekomendacja: Traefik — najmniej custom kodu.

1. DODAJ KALKULACJĘ KOSZTÓW — Przed implementacją oszacuj: 50 kontenerów × RAM (1-2GB) + CPU + pasmo. Wylicz próg rentowności przy $5/dzień i $15/tydzień.

1. DODAJ TIMEOUT PŁATNOŚCI — Scheduler powinien anulować zamówienia pending starsze niż np. 30 minut. Dodaj kolumnę payment_timeout_at do orders.

1. DOPRECYZUJ "1-hour buffer" — Określ, czy to czas na pierwsze logowanie, czy darmowy okres przed naliczeniem.

1. ROZWAŻ OPCJONALNY RECOVERY — Dodaj opcję ponownego wiązania urządzenia przez order number + potwierdzenie (np. 6-cyfrowy PIN na stronie zamówienia). To nie niszczy anonimowości, a ratuje UX.

1. DODAJ KRYTERIA AKCEPTACJI — Dla każdego głównego przepływu (zakup, aktywacja, sesja, wygaśnięcie, support) zapisz 3-5 warunków akceptacji.

1. DOPRECYZUJ ADMIN PANEL — Określ listę akcji, które admin może wykonać, oraz sposób autoryzacji.

1. DODAJ OBSŁUGĘ UNDERPAID — Gdy Trocador zwróci płatność niższą niż oczekiwano, ustaw status underpaid i wyślij alert.

Raport wygenerowany 2026-07-22 przez MOA (kimi-k3 + DeepSeek V4 Flash jako reference, DeepSeek V4 Flash jako aggregator).