# THECR3W-DEV — DOKUMENTACJA ARCHITEKTURY SYSTEMU ## Wersja: 1.0.0 | Data: 2026-10-31 --- ## 1. Wprowadzenie i Filozofia Architektury **TheCr3w-dev** to zintegrowany, samowystarczalny ekosystem zarządzania cyklem życia oprogramowania, dystrybucją aktualizacji aplikacji natywnych (Android, Windows), magazynowaniem artefaktów binarnych, orkiestracją wdrożeń kontenerowych Docker oraz synchronizacją serwerów zewnętrznych (SFTP/FTPS). Platforma została zaprojektowana w modelu **modularnego monolitu backendowego z rozdzielonymi domenowo interfejsami API oraz niezależnymi aplikacjami frontendowymi**: 1. **Separacja domenowa:** - **Native Update API (`app.thecr3wnet.com`):** Dystrybucja metadanych wydań, weryfikacja aktualizacji aplikacji Android/Windows, generowanie krótkotrwałych podpisanych adresów URL (Pre-signed S3) do Cloudflare R2, telemetria instalacji i błędów. - **Deployment Control API (`app.thecr3wnet.com/control`):** Rejestracja podpisanych manifestów wdrożeniowych, bramki zatwierdzania produkcji (Production Approval Gateways), zarządzanie immutable digestami Forgejo OCI, komunikacja z Deployment Agentem oraz synchronizacja SFTP/FTPS. 2. **Separacja frontendowa:** - **The Cr3w Download Center (`download.thecr3wnet.com`):** Lekki, w 100% publiczny portal prezentacji aplikacji i pobierania wydań. Brak bezpośredniego dostępu do bazy i sekretów R2; komunikacja wyłącznie przez publiczne REST API `app.thecr3wnet.com`. - **Admin Panel:** Chroniony interfejs administracyjny wykorzystujący protokół OIDC (Authorization Code Flow + PKCE) z istniejącym serwerem **Keycloak** (`login.thecr3wnet.com`, realm `master`). 3. **Domena bazowa `thecr3wnet.com`:** - Czysto infrastrukturalna domena brzegowa. Zgodnie z nadrzędnymi wytycznymi **nie posiada i nie będzie posiadać żadnej strony WWW, CMS ani landing page**. --- ## 2. Diagram Architektury Logicznej i Przepływu Danych ```mermaid flowchart TD subgraph Clients["Warstwa Klientów i Użytkowników"] PubUser["Użytkownik Końcowy (Download Center)"] AdminUser["Administrator / Release Manager (Admin Panel)"] AndroidSDK["Aplikacja Android (TheCr3w Kotlin SDK)"] WindowsSDK["Aplikacja Windows (TheCr3w .NET SDK)"] ForgejoCI["Forgejo Actions CI/CD"] end subgraph Ingress["Warstwa Brzegowa (Caddy Reverse Proxy)"] CaddyProxy["Caddy v2 (Docker Network: proxy)\nAutomatyczny TLS (Let's Encrypt / ZeroSSL)"] end subgraph IAM["Zarządzanie Tożsamością (Keycloak)"] Keycloak["Keycloak IAM (login.thecr3wnet.com)\nRealm: master | Client Roles"] end subgraph TheCr3wCore["Rdzeń Ekosystemu TheCr3w-dev (.NET 9 ASP.NET Core)"] NativeAPI["Native Update API\n(Updates, Releases, Download URLs)"] DeployAPI["Deployment Control API\n(Manifests, Approvals, Rollback)"] SharedDomain["TheCr3w.Shared.Domain & Crypto\n(Ed25519 Canonical Signing, SHA256)"] NativeAPI --- SharedDomain DeployAPI --- SharedDomain end subgraph DataStorage["Warstwa Danych i Magazynu"] PostgresDB[("PostgreSQL 16 Alpine\n(Dedykowana baza: thecr3w-postgres)\nWersjonowane migracje DDL")] R2Storage["Cloudflare R2 (S3-compatible)\nBucket: thecr3w-app\n(Prywatne binaria APK, EXE, MSI)"] end subgraph ExecutionPlane["Płaszczyzna Wykonawcza Wdrożeń"] DeployAgent["Deployment Agent\n(Izolowany demon z kontrolowaną białą listą operacji)"] DockerHost["Docker Engine (Netcup Host)"] ExternalSFTP["Zewnętrzne Serwery (SFTP / FTPS)"] end %% Ingress routing PubUser -->|download.thecr3wnet.com| CaddyProxy AdminUser -->|Admin UI OIDC| CaddyProxy AndroidSDK -->|app.thecr3wnet.com| CaddyProxy WindowsSDK -->|app.thecr3wnet.com| CaddyProxy ForgejoCI -->|Publikacja wydania / manifestu| CaddyProxy CaddyProxy --> NativeAPI CaddyProxy --> DeployAPI AdminUser -->|Uwierzytelnienie| Keycloak DeployAPI -.->|Weryfikacja JWT / JWKS| Keycloak NativeAPI -.->|Weryfikacja JWT / JWKS| Keycloak NativeAPI --- PostgresDB DeployAPI --- PostgresDB %% Magazyn R2 NativeAPI -->|Generowanie Pre-signed GET (15 min)| R2Storage NativeAPI -->|Generowanie Pre-signed PUT (Upload)| R2Storage PubUser -.->|Bezpośrednie pobieranie artefaktu| R2Storage AndroidSDK -.->|Bezpośrednie pobieranie artefaktu| R2Storage WindowsSDK -.->|Bezpośrednie pobieranie artefaktu| R2Storage %% Płaszczyzna wdrożeniowa DeployAPI -->|Podpisany manifest po akceptacji| DeployAgent DeployAgent -->|docker pull @sha256 & compose up| DockerHost DeployAPI -->|Synchronizacja ze sprawdzonym host-key| ExternalSFTP ``` --- ## 3. Model Kryptograficzny (Ed25519) W celu zapewnienia niezaprzeczalności i integralności wydań oraz manifestów wdrożeniowych stosowany jest algorytm **Ed25519** (RFC 8032): ### 3.1. Podpisywanie Metadanych Wydania (Native Release Metadata) 1. Podczas publikacji wydania w Native Update API tworzona jest kanoniczna postać JSON metadanych (uporządkowane alfabetycznie klucze, brak zbędnych białych znaków, kodowanie UTF-8): ```json {"app_id":"com.thecr3w.app","architecture":"arm64-v8a","channel":"stable","file_size":48921024,"mandatory":false,"minimum_supported_version":"1.0.0","platform":"android","published_at":"2026-10-31T12:00:00Z","release_id":"...","sha256":"...","version":"1.2.0","version_code":12} ``` 2. Metadane są podpisywane prywatnym kluczem Ed25519 przechowywanym wyłącznie w bezpiecznej konfiguracji backendu. 3. Klienci natywni (Android SDK oraz Windows SDK) posiadają zaszyty lub pobrany przez HTTPS publiczny klucz weryfikujący Ed25519. 4. **Warunek instalacji:** Klient natywny weryfikuje podpis Ed25519 metadanych oraz sumę SHA256 pobranego pliku przed zainicjowaniem instalacji. ### 3.2. Podpisywanie Manifestów Wdrożeniowych (Deployment Manifests) 1. Każdy manifest generowany w procesie CI/CD (lub przez uprawnionego inżyniera) zawiera `immutable_digest` obrazu z Forgejo OCI (`sha256:...`) oraz `config_hash`. 2. Manifest jest podpisywany kluczem Ed25519. 3. Przed wdrożeniem produkcyjnym zatwierdzający (Approver) podpisuje dokładny skrót SHA256 manifestu. Jeśli manifest ulegnie jakiejkolwiek zmianie po zatwierdzeniu, jego SHA256 zmienia się, a wdrożenie zostaje **automatycznie zablokowane**. --- ## 4. Architektura Ról RBAC i Integracja z Keycloak - **Instancja Keycloak:** `https://login.thecr3wnet.com` - **Realm:** `master` - **Klient OIDC Frontend (Admin Panel):** `thecr3w-admin-panel` (Typ: Public, PKCE: S256, Standard Flow) - **Klient OIDC Backend (API):** `thecr3w-backend` (Typ: Confidential, Bearer-only / Service Accounts) ### Separacja Ról Klienta (Client Roles w realm `master`): W celu eliminacji ryzyka eskalacji uprawnień w administracyjnym realm `master`, wszystkie role są definiowane wyłącznie w przestrzeni klienta `thecr3w-backend`: | Rola Klienta | Uprawnienia | |---|---| | `thecr3w:admin` | Pełne zarządzanie aplikacjami, konfiguracją, kluczami, serwerami zewnętrznymi oraz pełny audyt. | | `thecr3w:release-manager` | Tworzenie wydań (Draft), upload artefaktów do R2, podpisywanie i publikowanie wydań, wycofywanie wydań. | | `thecr3w:approver` | Zatwierdzanie wdrożeń produkcyjnych (podpisywanie SHA256 manifestów). | | `thecr3w:deployer` | Zgłaszanie manifestów wdrożeniowych, uruchamianie wdrożeń na staging/dev, podgląd i synchronizacja SFTP/FTPS. | | `thecr3w:viewer` | Dostęp tylko do odczytu: podgląd dashboardu, listy wydań, historii wdrożeń i logów audytowych. | --- ## 5. Integracja z Magazynem Cloudflare R2 - **Endpoint API S3:** `https://bf705752e38169fedb83efd5b747390e.r2.cloudflarestorage.com` - **Bucket:** `thecr3w-app` - **Polityka dostępu:** Prywatny bucket (Zero anonimowego listowania). - **Struktura kluczy obiektów w R2:** `apps/{app_id}/{platform}/{channel}/{version}_{version_code}_{arch}_{sha256_short}.{ext}` Przykład: `apps/com.thecr3w.app/android/stable/1.2.0_12_arm64-v8a_7a59d813.apk` - **Proces pobierania:** 1. Klient odpytuje `GET /api/v1/apps/{app_id}/releases/{release_id}/download`. 2. Backend weryfikuje status publikacji wydania i generuje Pre-signed S3 GET URL o ważności 900 sekund (15 minut). 3. Klient pobiera plik binarny bezpośrednio z Cloudflare CDN/R2 z pełną prędkością łącza i weryfikuje SHA256.