# THECR3W-DEV — INTEGRACJA CLOUDFLARE R2
## Wersja: 1.0.0 | Data: 2026-10-31

---

## 1. Parametry Połączeniowe

Na podstawie danych przekazanych przez Właściciela Projektu:
- **S3 API Endpoint:** `https://bf705752e38169fedb83efd5b747390e.r2.cloudflarestorage.com`
- **Bucket:** `thecr3w-app`
- **Region:** `auto` (domyślny dla Cloudflare R2)
- **Protokół:** Amazon S3 Signature Version 4 (SigV4)

Zmienne środowiskowe wymagane przez backend (wstrzykiwane wyłącznie na serwerze przez `.env` / Docker Compose):
```env
R2_ENDPOINT=https://bf705752e38169fedb83efd5b747390e.r2.cloudflarestorage.com
R2_BUCKET=thecr3w-app
R2_REGION=auto
R2_ACCESS_KEY_ID=<wstrzykiwane-z-bezpiecznego-magazynu>
R2_SECRET_ACCESS_KEY=<wstrzykiwane-z-bezpiecznego-magazynu>
```

> [!CAUTION]
> Klucze dostępowe `R2_ACCESS_KEY_ID` oraz `R2_SECRET_ACCESS_KEY` **NIGDY** nie mogą trafić do aplikacji frontendowych (The Cr3w Download Center, Admin Panel) ani aplikacji mobilnych/desktopowych (Android APK, Windows EXE).

---

## 2. Architektura Dostępu i Generowanie Pre-signed URLs

Wszystkie operacje I/O z Cloudflare R2 realizowane są w modelu Pre-signed URL:

```
[Klient: Android / Windows / Download Center]
        │
        │ 1. GET /api/v1/apps/{id}/releases/{release_id}/download
        ▼
[TheCr3w Native Update API]
        │
        │ 2. Weryfikacja publikacji w bazie PostgreSQL
        │ 3. Wyliczenie AWS SigV4 Pre-signed GET URL (ważność 15 minut)
        ▼
[Klient otrzymuje: URL, SHA256, Ed25519 Signature]
        │
        │ 4. Pobieranie binarne GET bezpośrednio z R2
        ▼
[Cloudflare R2 Storage (thecr3w-app)]
```

### 2.1. Pobieranie Artefaktów (Pre-signed GET)
- Czas wygasania: **900 sekund (15 minut)**.
- Adres URL jest ograniczony do konkretnego klucza obiektu.
- Użytkownik lub aplikacja natywna pobiera plik bezpośrednio z infrastruktury Cloudflare, nie obciążając procesora ani pasma serwera Netcup.

### 2.2. Upload Artefaktów (Pre-signed PUT)
- Inicjowany przez uprawnionego Release Managera lub Forgejo Actions CI/CD.
- Endpoint API: `POST /api/v1/admin/storage/upload-url`.
- Czas wygasania adresu URL uploadu: **1800 sekund (30 minut)**.
- Zawiera walidację oczekiwanego nagłówka `Content-Type` oraz maksymalnego rozmiaru pliku.