Audyt Jakości Specyfikacji v3: Browser-VPN SaaS

Data audytu: 2026-07-22

Dokument: docs/superpowers/specs/2026-07-22-browser-vpn-v3-design.md (278 linii, 14 sekcji)

Cel biznesowy: Poprawiona specyfikacja produktu Browser-VPN — hostowanego SaaS z anonimowym dostępem przez krypto-płatności, z wirtualną przeglądarką w kontenerze Docker.

Audyty bazowe: v1 (CEO, 6.3/10), v2 (s_1 MOA, 6/10), v3 (s_2 MOA, 6/10), v4 (s_3 MOA, 6.5/10), v5 (s_2 MOA, 7.7/10)

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

1. Wprowadzenie

Niniejszy raport stanowi szósty audyt jakości (v6) specyfikacji Browser-VPN SaaS. Ocenia dokument v3 — poprawioną wersję po audycie v5 (który ocenił v2 na 7.7/10). Dokument v3 adresuje 14 z 15 problemów zidentyfikowanych w raporcie v5, wprowadzając m.in. BTCPay integrację z detalami, secrets management, SLO/SLA, kryteria akceptacji dla 7 przepływów, admin panel z endpointami, rate limiting, Trivy scanning, PostgreSQL, seccomp profil, monitoring, CI/CD, API versioning i backup off-site.

Zakres audytu:

• Analiza strukturalna dokumentu v3 (278 linii, 14 sekcji zmian)
• Weryfikacja 14 zmian względem v2 i mapowanie na problemy z raportu v5
• Ocena wg 5 kryteriów: kompletność, spójność, mierzalność, wykonalność, bezpieczeństwo
• Porównanie v2 vs v3 — mapa problemów rozwiązanych, pozostałych i nowych
• Weryfikacja samooceny v3 (8.8/10) — czy jest uzasadniona?
• Konkretne rekomendacje przed implementacją

2. Podsumowanie wykonawcze i ocena ogólna

Specyfikacja v3 to znacząca poprawa względem v2 i najdokładniejsza wersja do tej pory. Adresuje 14 z 15 problemów z raportu v5 — od krytycznych (BTCPay detale, Selkies streaming) przez ważne (SLO, kryteria akceptacji, secrets management, admin panel, rate limiting, image scanning, CI/CD) po kosmetyczne (monitoring, seccomp, API versioning, backup frequency, database). Dokument jest konkretny, dobrze ustrukturyzowany i zawiera tabele, kod i przykłady konfiguracji.

Mimo to, dokument nie osiąga deklarowanej samooceny 8.8/10. Głównym problemem jest nieweryfikowana premisa architektoniczna: v3 deklaruje, że obrazy linuxserver.io (chrome, brave, firefox, mullvad-browser) mają wbudowany "WebRTC streaming przez Selkies-GStreamer" i "Port 3001 dla WebRTC (WebSocket)". Historycznie obrazy linuxserver.io używały KasmVNC/noVNC (port 3000), nie Selkies-GStreamer. Selkies-GStreamer to osobny projekt (github.com/selkies-project/selkies-gstreamer) wymagający własnej instalacji. Niezależnie od tego, czy nowsze wersje baseimages linuxserver.io zmigrowały na Selkies-GStreamer, premisa wymaga weryfikacji dla konkretnych tagów obrazów użytych w v3. Jeśli premisa jest błędna, cała architektura streamingu opiera się na nieistniejącej funkcjonalności.

Ponadto v3 wprowadza nowe luki niewystępujące w v5: brak polityki retencji danych (krytyczne dla produktu "total privacy"), brak opisu izolacji sieciowej między kontenerami, brak zarządzania konfiguracjami WireGuard, oraz sprzeczność w seccomp (profil "dołączony" ale "dla v2, nie MVP").

Scorecard — ocena wg wymiarów (skala 1-10)

Werdykt: Approve with conditions — dokument zatwierdzić do implementacji warunkowo, pod warunkiem: (1) weryfikacji czy linuxserver.io obrazy faktycznie dostarczają Selkies-GStreamer WebRTC, (2) doprecyzowania izolacji sieciowej między kontenerami, (3) dodania polityki retencji danych.

3. Analiza szczegółowa wg 5 kryteriów

3.1 Kompletność (8.5/10)

Co jest pokryte (nowe w v3):

• BTCPay Server integracja — pełne detale: webhook handling (4 eventy), failover flow z kodem Python, wspierane kryptowaluty, architektura routing przez Traefik
• Selkies-GStreamer — decyzja "dane" z uzasadnieniem: linuxserver images z noVNC + WebRTC, porty 3000/3001, Traefik labels
• Secrets management — tabela 7 sekretów z lokalizacją i metodą, rotacja co 90 dni
• SLO/SLA — 4 metryki: uptime 99.5%, start <60s P95, API <500ms P95, streaming <2s
• Kryteria akceptacji — 7 przepływów × 3 kryteria każda (zakup, płatność Trocador, płatność BTCPay, aktywacja, sesja, expiry, backup)
• Admin panel — 14 endpointów API z metodami HTTP, audit log do admin_audit_logs
• Rate limiting — 10 req/min + per-endpoint (orders 5/h, tickets 3/h, admin 30/min)
• Image scanning — Trivy weekly + alert Telegram + auto-rebuild
• Database — PostgreSQL + migracje SQL + backup pg_dump + GPG encrypt + rsync off-site
• Seccomp profil — lista syscalli (clone, futex, eventfd2, set_robust_list, prctl)
• Monitoring — 7 metryk co 30s + 10 alertów Telegram z progami i severity
• CI/CD — GitHub Actions: build → migrate → staging → smoke tests → production (manual gate)
• API versioning — /api/v1/ prefix, minor/major bump rules, deprecation 3 miesiące
• Backup off-site — co 6h, retention 7 dni lokalny + 30 dni off-site

Czego brakuje (pozostałe z v5):

• Diagram ERD — relacje między tabelami orders, sessions, tickets, vpn_configs nadal bez wizualizacji (C1 z v5)

Czego brakuje (nowe luki w v3):

• Polityka retencji danych — dla produktu "total privacy" brak definicji: jakie dane użytkownika są przechowywane, jak długo, prawo do usunięcia. Krytyczne dla produktu privacy-first.
• Izolacja sieciowa między kontenerami — jak kontenery są networkowane? Wspólny bridge? Czy kontener A może zobaczyć ruch kontenera B? Brak Docker network policy.
• Zarządzanie konfiguracjami WireGuard — jak configi VPN są generowane, rotowane, dystrybuowane do kontenerów? Admin panel ma endpoint /vpn-configs ale brak opisu lifecycle.
• Supply chain verification — Trivy skanuje podatności, ale brak weryfikacji podpisów obrazów (Cosign, Notary). Docker Hub bez podpisu = ryzyko supply chain attack.

3.2 Spójność (7.0/10)

Mocne strony:

• BTCPay failover flow jest wewnętrznie spójny — Trocador primary, 2 min timeout, BTCPay fallback, retry po 30s
• Secrets management tabela jest spójna — Docker secrets dla wrażliwych, .env dla mniej krytycznych, GPG key off-server
• SLO metryki są spójne z alertami (CPU >80% → WARN, container start >60s → WARN odpowiada SLO <60s P95)
• Rate limiting per-endpoint jest spójny z funkcjonalnością (orders 5/h = anti-spam, admin 30/min = wygoda)

Krytyczne niespójności:

• Selkies "dane" — nieweryfikowana premisa: v3 deklaruje że obrazy linuxserver.io mają "WebRTC streaming przez Selkies-GStreamer" i "Port 3001 dla WebRTC (WebSocket)". Historycznie obrazy linuxserver.io (linuxserver/chrome, linuxserver/firefox itd.) używały KasmVNC lub noVNC, nie Selkies-GStreamer. Selkies-GStreamer to osobny projekt (github.com/selkies-project/selkies-gstreamer) wymagający własnej instalacji w kontenerze. Jeśli premisa jest błędna, cała decyzja "Selkies nie wymaga implementacji" jest nieważna.
• Seccomp sprzeczność: v3 mówi "Dołączony profil seccomp dla kontenera przeglądarki" i listuje syscalls, ale następnie: "W praktyce --security-opt=seccomp=default + --cap-drop=ALL + --cap-add=NET_ADMIN,SYS_PTRACE + --no-new-privileges jest wystarczające dla MVP. Custom seccomp profil dla v2." — "dla v2" sugeruje że custom profil jest dla poprzedniej wersji, nie dla v3/MVP. Czy profil jest dołączony czy nie?
• Traefik port 3001 bez konfiguracji: v3 mówi "Port 3001 dla WebRTC (WebSocket)" ale Traefik labels konfigurują tylko loadbalancer.server.port=3000. Jak ruch na port 3001 jest routowany? WebRTC typowo używa UDP, które Traefik nie proxy'uje natywnie. Brak konfiguracji dla port 3001.
• API versioning v1.1 niejasny: v3 mówi "Non-breaking = minor bump (v1.1)" ale URL prefix to /api/v1/. Jak v1.1 manifestuje się w URL? Nadal /api/v1/? Nowy /api/v1.1/? Nieokreślone.

3.3 Mierzalność (8.0/10)

Co jest mierzalne (nowe w v3):

• SLO: uptime 99.5% (health check co 30s), start <60s P95, API <500ms P95, streaming <2s
• Kryteria akceptacji: 7 flowów × 3 konkretne kryteria (np. "POST /api/v1/orders zwraca 201 z order_number")
• Rate limiting: 10 req/min average, 20 burst, per-endpoint limity
• Backup: co 6h, retention 7/30 dni
• Secrets rotacja: co 90 dni
• Trivy scanning: weekly + na upstream release
• Alert progi: CPU >80%, RAM >80%, disk <10%, container start >60s, itd.

Czego brakuje:

• Metodologia pomiaru SLO bez Prometheus: v3 mówi "Prometheus + Grafana (opcjonalnie, po MVP). Dla MVP: Traefik metrics + Telegram alerts." Ale jak mierzyć "container startup time (P95)" i "streaming latency <2s" bez Prometheus? Traefik metrics mierzy HTTP response time, nie czas startu kontenera ani latencję WebRTC.
• Smoke tests niezdefiniowane: CI/CD mówi "Run smoke tests (health check, create order, payment flow)" ale nie definiuje co stanowi passing test. Brak frameworka testowego, brak asercji.
• Streaming quality metryki: SLO mówi "<2s (WebRTC)" ale brak definicji jak mierzyć latencję WebRTC. Heartbeat co 30s mierzy czy kontener żyje, nie latencję streamingu.

3.4 Wykonalność (7.0/10)

Technologie znane i sprawdzone:

• PostgreSQL — dojrzały, powszechnie używany, migracje SQL to standard
• Trivy — dojrzały skaner obrazów, powszechnie używany w CI
• Docker secrets — natywna funkcja Docker Swarm, ale wymaga Swarm mode (nie standalone Docker). Jeśli stack używa docker-compose (nie Swarm), Docker secrets nie są dostępne — trzeba użyć secrets: w compose file z external: true lub alternatywy.
• BTCPay Server — dojrzały, self-hosted, ale wymaga Bitcoin node (przez pełny węzeł lub pruned) + Lightning node
• GitHub Actions — standard CI/CD, dobrze udokumentowany

Obszary ryzyka:

• BTCPay na single server: BTCPay Server z pełnym Bitcoin node wymaga ~500 GB dysku (blockchain) + 4-8 GB RAM. Na serwerze z 30 kontenerami przeglądarek (60 GB RAM) to dodatkowe obciążenie. Serwer 128 GB RAM (Hetzner AX102) może nie wystarczyć. Alternatywa: BTCPay w trybie "pruned node" lub połączenie z zewnętrznym Bitcoin node.
• SLO 99.5% na single server: 99.5% = ~43.8 godzin downtime/rok. Na single server bez HA, bez failover, każdy restart serwera, aktualizacja kernela, awaria dysku = downtime. Realistycznie 99.5% wymaga co najmniej 2 serwerów lub managed hosting z live migration.
• Docker secrets bez Swarm: Jeśli stack używa docker-compose (nie Docker Swarm), secrets: w compose file działa tylko w Swarm mode. W standalone mode trzeba użyć bind mount z plikiem lub alternatywy (Vault, sops, age-encrypted files).
• Selkies claim wymaga weryfikacji: Jeśli linuxserver.io obrazy NIE mają Selkies-GStreamer, trzeba zbudować własne obrazy z Selkies — to znaczący dodatkowy工作量.

3.5 Bezpieczeństwo (7.5/10)

Silne strony (nowe w v3):

• Secrets management — Docker secrets dla wrażliwych (webhook keys, TOTP), .env dla mniej krytycznych, GPG key off-server, rotacja co 90 dni
• Trivy image scanning — weekly + na upstream release, alert na CRITICAL/HIGH, auto-rebuild
• Admin audit log — admin_audit_logs (admin_id, action, target, timestamp, ip), wszystkie akcje logowane
• Rate limiting dostrojony — 10 req/min (zamiast 5 req/h) + per-endpoint, eliminuje fałszywe blokady
• PostgreSQL — dojrzała baza z lepszym bezpieczeństwem niż SQLite (auth, SSL, row-level security)
• Seccomp syscalls — konkretna lista (clone, futex, eventfd2, set_robust_list, prctl)

Słabe strony / luki:

• Brak izolacji sieciowej między kontenerami — dla produktu "total privacy" to krytyczne. Jeśli kontenery współdzielą Docker bridge network, jeden skompromitowany kontener może sniff'ować ruch innego. Brak Docker network policy, brak per-container network namespace isolation.
• Brak polityki retencji danych — produkt "total privacy" nie definiuje: jakie dane użytkownika są przechowywane (IP? fingerprint? historia sesji?), jak długo, prawo do usunięcia. Dla produktu privacy-first to fundamentalna luka.
• Brak supply chain verification — Trivy skanuje podatności, ale nie weryfikuje podpisów obrazów. Docker Hub obrazy bez Cosign/Notary = ryzyko tampered image.
• Docker secrets bez Swarm — jeśli stack nie używa Swarm mode, secrets management jest niekompletny. .env z szyfrowaniem jest wspomniane ale nie opisane (jak szyfrowane? age? sops?).
• BTCPay attack surface — BTCPay Server w tym samym stacku co browser containers zwiększa attack surface. BTCPay ma własne endpointy, własne zależności, własne podatności. Brak network isolation między BTCPay a browser containers.
• Database encryption at rest — PostgreSQL backup jest szyfrowany (GPG), ale sama baza na dysku nie jest szyfrowana. Brak LUKS, brak PostgreSQL TDE.

4. Lista problemów

KRYTYCZNY (blokuje implementację)

WAŻNY (istotne ryzyko)

KOSMETYCZNY (drobne poprawki)

5. Porównanie: v2 vs v3 — mapa problemów

Problemy rozwiązane (v2 → v3)

Problemy pozostałe (v2 → v3 nadal nierozwiązane)

Nowe problemy (v3)

6. Weryfikacja samooceny v3 (8.8/10)

v3 deklaruje "Szacowana ocena: 8.8/10". Niniejszy audyt ocenia v3 na 7.6/10. Różnica 1.2 punktu wynika z:

1. Samoocena nie weryfikuje premisy Selkies — v3 traktuje "linuxserver images mają Selkies-GStreamer" jako fakt, bez weryfikacji. Jeśli premisa jest błędna, cała architektura streamingu wymaga przebudowy.
2. Samoocena nie identyfikuje nowych luk — brak izolacji sieciowej, brak retencji danych, brak WireGuard config management to nowe problemy niewystępujące w v5.
3. Samoocena nie ocenia wykonalności SLO — 99.5% na single server bez HA jest ambitne, ale v3 traktuje to jako rozwiązane.
4. Samoocena nie zauważa sprzeczności — seccomp "dla v2", Traefik port 3001 bez konfiguracji, API versioning v1.1 niejasny.

Werdykt: Samoocena 8.8/10 jest przeszacowana o ~1.2 punktu. Dokument jest znaczącą poprawą, ale wymaga krytycznej weryfikacji przed implementacją.

7. Glosariusz

8. Źródła

Pliki źródłowe

• Specyfikacja v3: /root/browser-vpn-deploy/docs/superpowers/specs/2026-07-22-browser-vpn-v3-design.md (278 linii)
• Specyfikacja v2: /root/browser-vpn-deploy/docs/superpowers/specs/2026-07-22-browser-vpn-v2-design.md (296 linii)
• Specyfikacja v1: /root/browser-vpn-deploy/docs/superpowers/specs/2026-07-22-browser-vpn-product-design.md (738 linii)
• Raport v5: /root/convertere/reports/v5-private-browser.md (309 linii, 7.7/10)
• Raport bieżący (v6): /root/convertere/reports/v6-private-browser.md

Linki zewnętrzne

• BTCPay Server: https://btcpayserver.org/
• Trocador AnonPay: https://trocador.app/
• Selkies-GStreamer: https://github.com/selkies-project/selkies-gstreamer
• Linuxserver.io images: https://docs.linuxserver.io/
• KasmVNC (używany w linuxserver): https://kasmweb.com/kasmvnc
• Trivy scanner: https://aquasecurity.github.io/trivy/
• Cosign (supply chain): https://github.com/sigstore/cosign
• PostgreSQL: https://www.postgresql.org/
• Prometheus: https://prometheus.io/
• Docker secrets: https://docs.docker.com/engine/swarm/secrets/
• WireGuard: https://www.wireguard.com/

9. Rekomendacje

Przed implementacją (obowiązkowe)

1. Zweryfikuj premisę Selkies — sprawdź czy obrazy linuxserver.io (chrome, brave, firefox, mullvad-browser) faktycznie dostarczają Selkies-GStreamer WebRTC na porcie 3001. Jeśli nie: zbuduj własne obrazy z Selkies lub zmień architekturę streamingu na KasmVNC/noVNC (co linuxserver images już mają).
2. Dodaj izolację sieciową między kontenerami — każdy kontener w osobnej Docker network, brak współdzielenia bridge. Network policy: kontener może komunikować się tylko z WireGuard interface i Traefik proxy.
3. Dodaj politykę retencji danych — zdefiniuj: jakie dane użytkownika są przechowywane (IP? fingerprint? historia?), jak długo (session data: 30 dni po expiry, potem purge), prawo do usunięcia (endpoint lub automatyczny purge).

W pierwszym sprincie (zalecane)

1. Rozwiąż seccomp sprzeczność — zdecyduj: custom seccomp profil dla MVP czy --security-opt=seccomp=default? Usuń "dla v2" z dokumentu.
2. Skonfiguruj Traefik dla WebRTC — jeśli WebRTC jest używane, dodaj konfigurację dla port 3001 (UDP stream). Jeśli Traefik nie wspiera UDP proxy, rozważ bezpośredni dostęp lub STUN/TURN server.
3. Określ tryb Docker — jeśli używasz docker-compose (nie Swarm), zamień Docker secrets na alternatywę (sops + age-encrypted files, lub Hashicorp Vault).
4. Zdefiniuj smoke tests — określ framework (pytest? playwright?), asercje (health check 200, order creation 201, payment flow complete), co stanowi passing test.
5. Zweryfikuj wykonalność BTCPay na single server — oblicz zasoby: Bitcoin node (pruned: ~50 GB, full: ~500 GB) + Lightning + BTCPay app. Jeśli nie mieści się, użyj BTCPay w trybie "pruned" lub zewnętrznego Bitcoin node.

Drugi sprint (nice-to-have)

1. Diagram ERD dla tabel orders, sessions, tickets, vpn_configs
2. Dodaj Cosign podpisy obrazów (supply chain verification)
3. Database encryption at rest (LUKS lub PostgreSQL TDE)
4. Opisz lifecycle WireGuard configs (generacja, rotacja, dystrybucja do kontenerów)
5. Prometheus + Grafana dla pomiaru SLO (container startup time, streaming latency)

Koniec raportu v6. 2026-07-22.