Spaces:
Running on Zero
Running on Zero
docs: add Cloudflare Turnstile integration design spec
Browse files
docs/superpowers/specs/2026-10-07-cloudflare-turnstile-integration-design.md
ADDED
|
@@ -0,0 +1,177 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Desain Teknis: Integrasi Cloudflare Turnstile pada WhatsApp Full Profile Picture
|
| 2 |
+
|
| 3 |
+
**Tanggal:** 2026-10-07
|
| 4 |
+
**Status:** Disetujui
|
| 5 |
+
**Target Platform:** Backend (Hugging Face Spaces - Go), Frontend (Vercel - Vanilla JS/HTML/CSS)
|
| 6 |
+
|
| 7 |
+
---
|
| 8 |
+
|
| 9 |
+
## 1. Latar Belakang & Tujuan
|
| 10 |
+
Aplikasi **WhatsApp Full Profile Picture (ppfull)** memungkinkan pengguna mengunggah foto profil tanpa pemotongan (no-crop) dan menginstalnya langsung ke akun WhatsApp via session pairing / QR scan.
|
| 11 |
+
Untuk mencegah penyalahgunaan resource server, spam sesi WhatsApp, dan potensi serangan bot/DDoS terhadap backend di Hugging Face Spaces, sistem memerlukan mekanisme verifikasi bot modern dan ramah pengguna.
|
| 12 |
+
Dipilih **Cloudflare Turnstile** karena:
|
| 13 |
+
- Menghadirkan perlindungan tangguh tanpa membebani pengguna dengan puzzle/gambar CAPTCHA usang.
|
| 14 |
+
- Menggunakan mode *Managed* yang cepat dan seringkali lolos secara otomatis (smart invisible verification).
|
| 15 |
+
- Gratis dan didukung penuh oleh infrastruktur global Cloudflare.
|
| 16 |
+
|
| 17 |
+
---
|
| 18 |
+
|
| 19 |
+
## 2. Arsitektur Solusi
|
| 20 |
+
|
| 21 |
+
### 2.1 Alur Komunikasi Sistem
|
| 22 |
+
```
|
| 23 |
+
+-------------------------------------------------------------+
|
| 24 |
+
| Frontend (Vercel) |
|
| 25 |
+
+-------------------------------------------------------------+
|
| 26 |
+
| (1) GET /config (ambil TURNSTILE_SITE_KEY)
|
| 27 |
+
v
|
| 28 |
+
+-------------------------------------------------------------+
|
| 29 |
+
| Backend Go (Hugging Face) |
|
| 30 |
+
+-------------------------------------------------------------+
|
| 31 |
+
| (2) Response: { turnstile_enabled: true, turnstile_site_key: "..." }
|
| 32 |
+
v
|
| 33 |
+
+-------------------------------------------------------------+
|
| 34 |
+
| Frontend Render Turnstile Widget |
|
| 35 |
+
+-------------------------------------------------------------+
|
| 36 |
+
| (3) Interaksi user -> Cloudflare Turnstile API
|
| 37 |
+
v
|
| 38 |
+
+-------------------------------------------------------------+
|
| 39 |
+
| Cloudflare Turnstile Service |
|
| 40 |
+
+-------------------------------------------------------------+
|
| 41 |
+
| (4) Menghasilkan Turnstile Token ke Frontend
|
| 42 |
+
v
|
| 43 |
+
+-------------------------------------------------------------+
|
| 44 |
+
| Frontend Kirim WebSocket { action: "start" } |
|
| 45 |
+
| menyertakan payload `turnstile_token` |
|
| 46 |
+
+-------------------------------------------------------------+
|
| 47 |
+
| (5) WebSocket Connect & Send Init Message
|
| 48 |
+
v
|
| 49 |
+
+-------------------------------------------------------------+
|
| 50 |
+
| Backend Go (Hugging Face) |
|
| 51 |
+
| Memverifikasi token ke Cloudflare Siteverify API |
|
| 52 |
+
+-------------------------------------------------------------+
|
| 53 |
+
| (6) POST https://challenges.cloudflare.com/turnstile/v0/siteverify
|
| 54 |
+
v
|
| 55 |
+
+-------------------------------------------------------------+
|
| 56 |
+
| Cloudflare Turnstile Siteverify |
|
| 57 |
+
+-------------------------------------------------------------+
|
| 58 |
+
| (7) Response: { "success": true }
|
| 59 |
+
v
|
| 60 |
+
+-------------------------------------------------------------+
|
| 61 |
+
| Backend Loloskan Verifikasi |
|
| 62 |
+
| Inisialisasi Whatsmeow & Sesi WhatsApp Dimulai |
|
| 63 |
+
+-------------------------------------------------------------+
|
| 64 |
+
```
|
| 65 |
+
|
| 66 |
+
---
|
| 67 |
+
|
| 68 |
+
## 3. Spesifikasi Komponen
|
| 69 |
+
|
| 70 |
+
### 3.1 Backend Go (`main.go`)
|
| 71 |
+
|
| 72 |
+
#### Variabel Lingkungan (*Environment Variables*)
|
| 73 |
+
- `TURNSTILE_SITE_KEY`: Public site key dari Cloudflare Dashboard.
|
| 74 |
+
- `TURNSTILE_SECRET_KEY`: Secret key dari Cloudflare Dashboard.
|
| 75 |
+
|
| 76 |
+
#### Endpoint `GET /config`
|
| 77 |
+
- Menangani permintaan konfigurasi publik dari frontend.
|
| 78 |
+
- Mengembalikan response JSON:
|
| 79 |
+
```json
|
| 80 |
+
{
|
| 81 |
+
"turnstile_enabled": true,
|
| 82 |
+
"turnstile_site_key": "0x4AAAAAA..."
|
| 83 |
+
}
|
| 84 |
+
```
|
| 85 |
+
- **Aturan Mode**:
|
| 86 |
+
- `turnstile_enabled` adalah `true` jika `TURNSTILE_SITE_KEY` dan `TURNSTILE_SECRET_KEY` tidak kosong.
|
| 87 |
+
- Jika `TURNSTILE_SECRET_KEY` kosong, `turnstile_enabled` bernilai `false` (Dev/Bypass Mode).
|
| 88 |
+
|
| 89 |
+
#### Pembaruan Struct Payload WebSocket
|
| 90 |
+
```go
|
| 91 |
+
type WSIncomingMessage struct {
|
| 92 |
+
Action string `json:"action"` // "start"
|
| 93 |
+
Image string `json:"image"` // Base64 data URL
|
| 94 |
+
PairNumber string `json:"pair_number"` // Opsional
|
| 95 |
+
TurnstileToken string `json:"turnstile_token"` // Token Turnstile
|
| 96 |
+
}
|
| 97 |
+
```
|
| 98 |
+
|
| 99 |
+
#### Logika Verifikasi Token (`verifyTurnstileToken`)
|
| 100 |
+
```go
|
| 101 |
+
type TurnstileVerifyResponse struct {
|
| 102 |
+
Success bool `json:"success"`
|
| 103 |
+
ChallengeTS time.Time `json:"challenge_ts"`
|
| 104 |
+
Hostname string `json:"hostname"`
|
| 105 |
+
ErrorCodes []string `json:"error-codes"`
|
| 106 |
+
Action string `json:"action"`
|
| 107 |
+
Cdata string `json:"cdata"`
|
| 108 |
+
}
|
| 109 |
+
```
|
| 110 |
+
- **URL Verifikasi**: `https://challenges.cloudflare.com/turnstile/v0/siteverify`
|
| 111 |
+
- **Metode**: `POST` dengan `application/x-www-form-urlencoded`
|
| 112 |
+
- Parameter: `secret`, `response` (token), `remoteip` (opsional).
|
| 113 |
+
- **Aturan Keputusan**:
|
| 114 |
+
1. Jika `TURNSTILE_SECRET_KEY` tidak disetel: Log warning `[Turnstile] Secret key kosong, verifikasi di-bypass untuk dev`, kembalikan `nil` (lolos).
|
| 115 |
+
2. Jika `turnstile_token` kosong saat `TURNSTILE_SECRET_KEY` aktif: Tolak koneksi.
|
| 116 |
+
3. Jika panggilan HTTP gagal atau Cloudflare mengembalikan `success: false`: Tolak koneksi dan kirim pesan error:
|
| 117 |
+
`Verifikasi keamanan Turnstile gagal atau kedaluwarsa. Silakan muat ulang halaman.`
|
| 118 |
+
4. Jika `success: true`: Lanjutkan pemrosesan sesi Whatsmeow.
|
| 119 |
+
|
| 120 |
+
---
|
| 121 |
+
|
| 122 |
+
### 3.2 Frontend Vercel (`frontend/`)
|
| 123 |
+
|
| 124 |
+
#### 1. `frontend/index.html`
|
| 125 |
+
- Memuat skrip Cloudflare Turnstile di `<head>` dengan mode `render=explicit`:
|
| 126 |
+
```html
|
| 127 |
+
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit" async defer></script>
|
| 128 |
+
```
|
| 129 |
+
- Menambahkan kontainer widget di dalam formulir upload tepat sebelum tombol aksi:
|
| 130 |
+
```html
|
| 131 |
+
<div id="turnstile-wrapper" class="turnstile-wrapper hidden">
|
| 132 |
+
<div id="turnstile-widget"></div>
|
| 133 |
+
<div id="turnstile-status" class="turnstile-note"></div>
|
| 134 |
+
</div>
|
| 135 |
+
```
|
| 136 |
+
|
| 137 |
+
#### 2. `frontend/app.js`
|
| 138 |
+
- **State Management**:
|
| 139 |
+
- Menyimpan `turnstileWidgetId: null`, `turnstileToken: null`, `turnstileEnabled: false`.
|
| 140 |
+
- **Inisialisasi**:
|
| 141 |
+
- Setelah `checkBackendHealth()` berhasil, panggil `fetchConfig()`.
|
| 142 |
+
- Jika backend mengembalikan `turnstile_enabled: true` dan ada `turnstile_site_key`:
|
| 143 |
+
- Tampilkan `#turnstile-wrapper`.
|
| 144 |
+
- Panggil `turnstile.render('#turnstile-widget', { sitekey, callback, 'expired-callback', 'error-callback', theme: 'dark' })`.
|
| 145 |
+
- Jika `turnstile_enabled: false`:
|
| 146 |
+
- Sembunyikan `#turnstile-wrapper` dan izinkan proses berjalan langsung.
|
| 147 |
+
- **Validasi Tombol "Mulai Hubungkan"**:
|
| 148 |
+
- Tombol aktif jika `state.currentImageBase64` ada DAN (`!state.turnstileEnabled` ATAU `state.turnstileToken` valid).
|
| 149 |
+
- **Pengiriman Pesan WebSocket**:
|
| 150 |
+
- Sertakan `turnstile_token: state.turnstileToken` dalam payload `{ action: 'start' }`.
|
| 151 |
+
- Setelah proses dimulai atau jika error, reset widget turnstile agar token tidak dipakai ulang (*one-time use*).
|
| 152 |
+
|
| 153 |
+
#### 3. `frontend/style.css`
|
| 154 |
+
- Menata `#turnstile-wrapper` dengan padding, border glassmorphism, dan alignment tengah yang rapi dan elegan sesuai tema *dark mode*.
|
| 155 |
+
|
| 156 |
+
---
|
| 157 |
+
|
| 158 |
+
## 4. Keamanan & Penanganan Edge Cases
|
| 159 |
+
|
| 160 |
+
| Skenario | Penanganan |
|
| 161 |
+
|---|---|
|
| 162 |
+
| Token Kedaluwarsa (Expired) | Turnstile `expired-callback` otomatis mengosongkan state token dan meminta user mengklik/verifikasi ulang widget. |
|
| 163 |
+
| Replay Attack (Token Dipakai Ulang) | Cloudflare API otomatis menolak token yang sudah pernah divalidasi. Backend menolak request dan memutus sesi. |
|
| 164 |
+
| Backend Offline / Sleeping di Hugging Face | Widget tidak dirender hingga backend bangun (`/health` & `/config` sukses 200). Tombol aksi dinonaktifkan dengan status *"Membangunkan Server..."*. |
|
| 165 |
+
| Local Development (Tanpa Akun Cloudflare) | Tanpa mengisi `TURNSTILE_SECRET_KEY` di `.env`, backend otomatis aktif dalam Dev Mode (bypassed), pengembang tetap bisa coding lokal tanpa error. |
|
| 166 |
+
|
| 167 |
+
---
|
| 168 |
+
|
| 169 |
+
## 5. Rencana Pengujian
|
| 170 |
+
1. **Unit Test Go**:
|
| 171 |
+
- `main_test.go` untuk menguji fungsi `verifyTurnstileToken` (kondisi bypass, token kosong, payload mock).
|
| 172 |
+
- Test endpoint `GET /config` untuk memastikan JSON response sesuai format.
|
| 173 |
+
2. **Build Verification**:
|
| 174 |
+
- Menjalankan `go build` untuk memastikan tidak ada kesalahan kompilasi.
|
| 175 |
+
3. **Integrasi & Pengujian Browser**:
|
| 176 |
+
- Verifikasi bahwa frontend memuat widget jika key disediakan.
|
| 177 |
+
- Verifikasi bahwa backend menerima token melalui WebSocket dan memprosesnya dengan benar.
|