tempmail-worker

Panduan install, setup secrets, permission Cloudflare token, migrasi DB, dan deploy.

1) Prasyarat

• Node.js 20+
• npm
• Akun Cloudflare (sudah punya zone/domain)
• D1 database tempmail-db sudah dibuat dan dibinding ke worker

2) Install dependency

cd "D:\Project\Server 2\Server4\Cloudflare-Mail\tempmail-worker"
npm install

Gunakan npx wrangler ... (bukan wrangler ...) kalau wrangler tidak terpasang global.

3) Login Cloudflare CLI

npx wrangler login
npx wrangler whoami

4) Setup schema auth di D1

Jalankan migrasi auth table:

npx wrangler d1 execute tempmail-db --file=./schema.auth.sql --remote

Kalau ingin local D1 (tanpa remote):

npx wrangler d1 execute tempmail-db --file=./schema.auth.sql

4.1) Setup schema email di D1

Jalankan migrasi table emails (inbox pesan):

npx wrangler d1 execute tempmail-db --file=./schema.emails.sql --remote

Isinya:

• Tabel emails (recipient, sender, subject, body_text, body_html, created_at)
• Index idx_emails_created_at untuk sortir DESC cepat
• Index idx_emails_recipient_lower untuk lookup per-mailbox (WHERE lower(recipient) = lower(?))

Hemat D1 row-read

Worker punya 3 optimasi biar tidak jebol Rows read / day (limit 5M/bulan di free plan):

1. Module-level memo untuk ensureAuthSchema & ensureBootstrapAdmin — jalan sekali per isolate.
2. Cache getAdminSettings 10 detik (TTL di memori isolate).
3. Fast-path ?partial=inbox — auto-refresh inbox cuma butuh 1 D1 read (SELECT emails) tanpa schema bootstrap / admin settings / audit log.
4. Auto-refresh 30 detik (visibility-aware) + countdown UI. Pause saat tab tersembunyi.

5) Ambil credential/token dari provider

A. Cloudflare API Token (CF_API_TOKEN)

Path dashboard:

1. Cloudflare Dashboard
2. Klik avatar kanan atas
3. My Profile
4. API Tokens
5. Create Token
6. Pilih Create Custom Token

Permission minimal yang dibutuhkan

• Zone → Zone → Read
• Zone → DNS → Edit
• Zone → Email Routing Rules → Edit

Opsional (kalau nanti butuh inspeksi worker):

• Account → Workers Scripts → Read

Zone Resources

• Bisa pilih All zones (kalau kamu kelola banyak domain)
• Atau Include specific zone untuk keamanan lebih ketat

Selesai create, copy token (muncul sekali).

B. Zone ID (CF_ZONE_ID) - Opsional

Kalau token kamu pakai All zones, CF_ZONE_ID boleh dikosongkan.

Kalau mau lock ke satu zone saja, ambil dari:

1. Cloudflare Dashboard
2. Pilih domain/zone
3. Halaman Overview
4. Copy nilai Zone ID

C. Google OAuth

Path:

1. https://console.cloud.google.com/
2. APIs & Services → OAuth consent screen (setup dulu)
3. Credentials → Create Credentials → OAuth client ID
4. Type: Web application
5. Redirect URI:
   • https://<domain-worker>/auth/callback/google

Ambil:

• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• GOOGLE_REDIRECT_URI

D. GitHub OAuth

Path:

1. GitHub → Settings
2. Developer settings
3. OAuth Apps
4. New OAuth App
5. Callback URL:
   • https://<domain-worker>/auth/callback/github

Ambil:

• GITHUB_CLIENT_ID
• GITHUB_CLIENT_SECRET
• GITHUB_REDIRECT_URI

E. Discord OAuth

Path:

1. https://discord.com/developers/applications
2. Create application
3. OAuth2
4. Tambah redirect:
   • https://<domain-worker>/auth/callback/discord

Ambil:

• DISCORD_CLIENT_ID
• DISCORD_CLIENT_SECRET
• DISCORD_REDIRECT_URI

F. Bootstrap admin

Bikin sendiri:

• BOOTSTRAP_ADMIN_EMAIL
• BOOTSTRAP_ADMIN_USERNAME
• BOOTSTRAP_ADMIN_PASSWORD

G. Session secret

Generate random value:

[System.Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32))

Simpan sebagai SESSION_SECRET.

6) Cara masukin env/secrets

6.1 Local dev (.dev.vars)

1. Copy template:

copy .dev.vars.example .dev.vars

2. Buka file .dev.vars, lalu isi value asli. Contoh:

BOOTSTRAP_ADMIN_EMAIL=admin@domainkamu.com
BOOTSTRAP_ADMIN_USERNAME=admin
BOOTSTRAP_ADMIN_PASSWORD=PasswordKuat123!
CF_API_TOKEN=isi_token_dari_cloudflare
SESSION_SECRET=isi_random_secret

CF_ZONE_ID tidak perlu diisi kalau CF_API_TOKEN diberi akses All zones.

3. Jalankan local:

npm run dev

6.2 Production (Cloudflare secrets)

Jalankan command ini satu per satu. Setelah enter, CLI akan tampil prompt: 🌀 Enter a secret value: Lalu paste valuenya, enter lagi.

npx wrangler secret put CF_API_TOKEN
npx wrangler secret put CF_ZONE_ID
npx wrangler secret put BOOTSTRAP_ADMIN_EMAIL
npx wrangler secret put BOOTSTRAP_ADMIN_USERNAME
npx wrangler secret put BOOTSTRAP_ADMIN_PASSWORD
npx wrangler secret put SESSION_SECRET

npx wrangler secret put GOOGLE_CLIENT_ID
npx wrangler secret put GOOGLE_CLIENT_SECRET
npx wrangler secret put GOOGLE_REDIRECT_URI

npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
npx wrangler secret put GITHUB_REDIRECT_URI

npx wrangler secret put DISCORD_CLIENT_ID
npx wrangler secret put DISCORD_CLIENT_SECRET
npx wrangler secret put DISCORD_REDIRECT_URI

Opsional:

npx wrangler secret put API_KEY
npx wrangler secret put ADMIN_PASSWORD

Jika API key digunakan, endpoint API dapat diauthorize dengan salah satu cara berikut:

• Header x-api-key: API_KEY_ANDA
• Header Authorization: Bearer API_KEY_ANDA
• Query string ?api_key=API_KEY_ANDA

Contoh panggilan API:

curl -H "x-api-key: API_KEY_ANDA" "http://mail.zcus.biz.id/api/messages/user@gpt.zzzza.biz.id"

curl "http://mail.zcus.biz.id/api/messages/user@gpt.zzzza.biz.id?api_key=API_KEY_ANDA"

// Node.js
const target = 'user@gpt.zzzza.biz.id';
const res = await fetch(`http://mail.zcus.biz.id/api/messages/${encodeURIComponent(target)}`, {
  headers: { 'x-api-key': API_KEY }
});
console.log(await res.json());

# Python
import requests
API_KEY = 'API_KEY_ANDA'
target = 'user@gpt.zzzza.biz.id'
res = requests.get(
    f'http://mail.zcus.biz.id/api/messages/{requests.utils.requote_uri(target)}',
    headers={'x-api-key': API_KEY}
)
print(res.json())

// PHP
$apiKey = 'API_KEY_ANDA';
$target = 'user@gpt.zzzza.biz.id';
$ch = curl_init('http://mail.zcus.biz.id/api/messages/' . urlencode($target));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['x-api-key: ' . $apiKey]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
var_dump(json_decode($response, true));

Verifikasi secret sudah masuk:

npx wrangler secret list

Jangan simpan token/secret di wrangler.jsonc atau commit ke git.

7) Jalankan local

npm run dev

7.1) Jalankan test

npm test

Test jalan local mode (Miniflare D1 in-memory) — tidak perlu login Cloudflare. vitest.config.js set remoteBindings: false supaya tidak hit D1 remote.

8) Deploy

npm run deploy

9) Troubleshooting

wrangler not recognized

Gunakan npx:

npx wrangler --version

wrangler secret put ... gagal

• Pastikan sudah login: npx wrangler whoami
• Pastikan di folder project yang benar
• Pastikan worker name pada wrangler.jsonc sesuai

D1 execute gagal

• Pastikan DB binding ada di wrangler.jsonc
• Pastikan nama DB di command benar: tempmail-db
• Coba jalankan ulang dengan npx

zcus-mail