144 lines
8.3 KiB
Markdown
144 lines
8.3 KiB
Markdown
# 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.
|