ilhamdev commited on
Commit
64673d9
·
1 Parent(s): f56a6c7

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.