veritanet/README.md

Projekt: Prywatna Sieć Współpracy (na OpenZiti)

1. Cel i założenia

• Stworzenie prywatnej, szyfrowanej sieci dla ograniczonej grupy członków, niewidocznej z internetu (brak otwartych portów, usługi „znikają” z clearnetu).
• Zapewnienie bezpiecznej przestrzeni do:
  • współpracy nad kodem źródłowym,
  • pracy nad dokumentami/opracowaniami,
  • przetwarzania wrażliwych danych finansowych,
  • prowadzenia głosowań i delegacji głosów.
• Każdy członek posiada jeden główny identyfikator kryptograficzny, używany do podpisów (głosowanie, delegacja) oraz powiązany z jego tożsamością sieciową.
• Priorytety: prywatność, niedostępność usług z zewnątrz, silne tożsamości i granularne uprawnienia; anonimowość nie jest celem nadrzędnym.

---

2. Warstwa sieciowa - OpenZiti

2.1. Uzasadnienie wyboru

• OpenZiti opiera się na silnych, kryptograficznych tożsamościach, a nie na IP.
• Brak otwartych portów - usługi są niewidoczne dla skanerów, ruch odbywa się przez overlay i prywatny DNS.
• Możliwość pracy w trybie:
  • ZTAA - SDK w aplikacjach, process-to-process, E2E szyfrowanie i deny-by-default na firewallach.
  • ZTHA/ZTNA - tunelery i routery dla hostów/usług bez natywnego SDK.
• Private DNS + single-port transport, co ułatwia ukrycie topologii i minimalizuje powierzchnię ataku.

2.2. Komponenty OpenZiti

• Controller

  • Centralny punkt zarządzania tożsamościami, usługami i politykami.
  • Uruchomiony na zaufanym serwerze (VPS / bare-metal) z backupem i monitoringiem.

• Edge Routers (fabric)

  • 3-5 routerów w różnych lokalizacjach (różne DC/regiony), zapewniających redundancję i lepszą latencję.
  • Wystawione na świat jednym portem (single-port transport).
  • Pomiędzy routerami skonfigurowane połączenia dla pełnej siatki lub dobrze przemyślanej topologii (mesh / partial mesh).

• Ziti Tunneler / SDK

  • Klienci użytkowników (laptopy/desktopy) - tunneler albo natywna integracja z SDK (Ziti w aplikacji).
  • Serwery usług - albo także tunneler, albo integracja SDK w aplikacjach własnych.

---

3. Model tożsamości

3.1. Identyfikator główny członka

• Każdy członek ma główny klucz kryptograficzny (root key), przechowywany najlepiej na urządzeniu sprzętowym (YubiKey / HSM).
• Root key służy do:
  • podpisywania głosów i delegacji,
  • autoryzacji żądań wydania/odnowienia tożsamości sieciowej (opcjonalnie).

3.2. Tożsamość w OpenZiti

• Dla każdego członka tworzone jest identity w OpenZiti:
  • certyfikat + klucze używane w sieci,
  • przypisane atrybuty/role (np. member, core-dev, finance, board, observer).
• Powiązanie:
  • albo bezpośrednie (ten sam materiał klucza, jeśli akceptujemy to ryzyko),
  • albo pośrednie: cert Ziti zawiera referencję (np. fingerprint publicznego root key), a mapowanie jest przechowywane w rejestrze członków.

3.3. Role i atrybuty

Przykładowy zestaw:

• member - podstawowy członek wspólnoty.
• core-dev - rdzeń zespołu developerskiego.
• dev - pozostali developerzy.
• editor - osoby piszące/edycyjne (dokumenty).
• finance - zespół finansowy.
• board - gremium decyzyjne.
• voting-node - techniczne węzły obsługujące logikę głosowań.
• observer - dostęp tylko do odczytu, np. do wybranych repo / dokumentów.

---

4. Architektura logiczna

4.1. Typy węzłów

• Węzły członków (end-user)

  • Laptop/desktop z zainstalowanym Ziti tunnelerem lub aplikacjami z SDK.
  • Łączą się z fabricem przez wybrany edge router (automatycznie, wg health/latency).

• Węzły usługowe

  • Serwery repozytoriów, dokumentów, finansów, komunikacji.
  • Zwykle w jednym lub kilku zaufanych DC, tylko w overlay (brak publicznego nasłuchu HTTP/SSH itp.).

• Węzły specjalne (voting, governance)

  • Node'y operujące na protokole głosowania/delegacji, również w overlay.
  • Mogą być rozmieszczone geograficznie podobnie jak edge routery.

4.2. Główne usługi

• git-core - serwis repozytoriów kodu (np. Gitea/Forgejo/GitLab CE).
• docs - serwis dokumentów (np. Nextcloud, własny editor itp.).
• finance-api - backend do obsługi danych finansowych i raportów.
• chat - komunikacja (np. Matrix, Zulip, custom chat API).
• voting-api - serwis przyjmujący i weryfikujący głosy/delegacje, trzymający append-only log.

Każda z tych usług istnieje tylko jako Ziti service, z własnym wpisem w prywatnym DNS i bez ekspozycji na clearnet.

---

5. Polityki dostępu (Zero Trust)

Przykładowe polityki w Ziti:

• Service git-core
  • Access roles: core-dev, dev (RW), observer (RO).
• Service docs
  • Access roles: member (RO), editor (RW), board (full access).
• Service finance-api
  • Access roles: finance, board.
• Service chat
  • Access roles: member (pełny udział).
• Service voting-api
  • Access roles (klienci): member.
  • Access roles (węzły przetwarzające): voting-node, board (np. do widoków audytowych).

Dostęp oparty wyłącznie na identity + rolach, nie na IP, z enforcementem na poziomie OpenZiti.

---

6. Przepływy (flows) - jak to działa

6.1. Dołączanie nowego członka

1. Kandydat przechodzi proces akceptacji wewnętrzny (poza zakresem tego dokumentu).
2. Generuje swój root key (preferowany: na urządzeniu sprzętowym).
3. Przekazuje swój publiczny klucz root do „rejestru członków” (np. specjalny serwis administracyjny).
4. Administrator (lub automatyczny workflow) tworzy:
   • wpis członka w rejestrze,
   • tożsamość w OpenZiti z nadanymi rolami.
5. Członek otrzymuje bezpieczny token lub CSR-based enrollment, używa Ziti CLI/GUI do pobrania certów/identity.
6. Od tego momentu może łączyć się do sieci (po zalogowaniu i aktywnym tunnelerze lub aplikacji SDK).

6.2. Dostęp do usług

• Użytkownik uruchamia klienta (tunneler/app).
• Następuje uwierzytelnienie w Ziti przy użyciu jego identity.
• Private DNS zwraca adresy usług git-core, docs, finance-api, chat, voting-api jako tunele overlay.
• OpenZiti sprawdza polityki; tylko dopuszczone usługi są widoczne dla tożsamości.

6.3. Głosowanie i delegacja

• Uczestnik tworzy głos/delegację w swoim kliencie, podpisuje go root key.
• Klient przesyła głos do voting-api przez overlay (Ziti).
• voting-api:
  • weryfikuje podpis w oparciu o publiczny klucz z rejestru członków,
  • zapisuje rekord w append-only logu (np. z dodatkowym podpisem węzła voting-node).
• Delegacje mogą być przechowywane w tym samym systemie, a logika „kto głosuje za kogo” implementowana w warstwie aplikacyjnej voting-api.

---

7. Bezpieczeństwo i prywatność

• Brak otwartych portów - wszystkie usługi są dostępne wyłącznie przez fabric OpenZiti.
• End-to-end szyfrowanie (libsodium) pomiędzy procesami klienckimi i serwerowymi.
• Deny-by-default na poziomie:
  • firewalli sieciowych (otwarty tylko port Ziti),
  • polityk OpenZiti (nic nie jest dostępne bez przypisania).
• Dane w spoczynku:
  • repozytoria, dokumenty, bazy danych finansowe i log głosowań szyfrowane na poziomie storage (np. LUKS) i/lub aplikacji.
• Audyt:
  • logi z voting-api, finance-api i systemów repo/dokumentów zrzucane do odseparowanego systemu logów (również w overlay).

---

8. Minimalne MVP

1. Postawienie controller + min. 3 edge routerów OpenZiti (community self-hosted).
2. Zdefiniowanie podstawowych ról (member, core-dev, finance, board, observer, editor, voting-node).
3. Uruchomienie usług:
   • Gitea/Forgejo jako git-core,
   • Nextcloud jako docs,
   • prosty chat (np. Matrix server),
   • wstępne voting-api (minimalny protokół głosu/delegacji).
4. Zdefiniowanie polityk dostępu do powyższych usług w OpenZiti.
5. Przyjęcie pierwszych kilku członków i przetestowanie:
   • dołączenia do sieci,
   • dostępu do usług,
   • oddania głosu/delegacji.

---

9. Kierunki rozwoju

• Integracja SDK Ziti bezpośrednio w voting-api i innych usługach własnych (ZTA A).
• Automatyzacja onboardingu (portal członkowski, workflow z podpisem root key).
• Rozbudowa governance (różne typy głosowań, quorum, rotacja ról).
• Hardening:
  • HSM dla kluczy serwerowych,
  • dodatkowe polityki posturalne (wymogi co do OS/wersji/komponentów na maszynach członków).
• Opcjonalnie: dodatkowe warstwy prywatności (np. mieszanie ruchu dla wybranych operacji finansowych, jeśli kiedyś stanie się to celem).