Hardening Gateway untuk OpenRouter Fusion API: Auth, Secret, dan Rate Limit

Jika aplikasi Anda mengakses OpenRouter Fusion API, langkah paling aman bukan menghubungkan klien langsung ke upstream, melainkan menempatkan gateway backend di depannya. Gateway ini menjadi titik kontrol untuk autentikasi, penyimpanan secret, validasi input, rate limit, logging, dan penanganan error agar API key upstream tidak bocor dan trafik tidak mudah disalahgunakan.

Panduan ini berfokus pada hardening gateway untuk OpenRouter Fusion API dalam konteks produksi. Tujuannya praktis: memisahkan API key secara server-side, membatasi payload, memetakan session ke token internal, mencegah abuse seperti replay dan burst traffic, serta menjaga observability tanpa membocorkan data sensitif.

Arsitektur yang Direkomendasikan

Prinsip utamanya sederhana: klien tidak pernah mengetahui API key upstream. Semua request dari web, mobile, atau service lain masuk ke gateway Anda terlebih dahulu. Gateway memverifikasi identitas pemanggil, menerapkan policy, lalu meneruskan request yang sudah disanitasi ke OpenRouter Fusion API.

Alur request yang aman

Klien login ke sistem Anda dan memperoleh session atau token aplikasi internal.
Klien memanggil endpoint gateway, misalnya POST /ai/generate.
Gateway memverifikasi session/token, memetakan user ke policy, lalu memeriksa rate limit per user dan per IP.
Gateway memvalidasi payload: ukuran body, tipe konten, field wajib, batas panjang prompt, dan parameter yang diizinkan.
Gateway menambahkan kredensial upstream dari secret store server-side.
Gateway meneruskan request ke OpenRouter Fusion API melalui koneksi outbound yang terkontrol.
Gateway menerima respons, menghapus detail sensitif/error internal upstream bila perlu, lalu mengembalikan respons aman ke klien.
Gateway menulis audit log terstruktur tanpa menyimpan secret atau prompt penuh yang sensitif.

Komponen minimum

API gateway/backend service untuk auth, validation, rate limit, proxying.
Secret manager atau environment injection yang terkontrol.
Store untuk rate limit dan idempotency, umumnya Redis atau penyimpanan in-memory terdistribusi.
Audit log terstruktur yang terhubung ke sistem logging/monitoring.
Alerting untuk lonjakan trafik, kegagalan upstream, dan percobaan abuse.

Threat Model: Risiko yang Perlu Diantisipasi

Sebelum menulis middleware, tentukan ancaman apa yang benar-benar ingin Anda cegah. Untuk integrasi semacam ini, ancaman yang paling umum adalah sebagai berikut.

1. Kebocoran API key upstream

Ini risiko paling jelas. Jika API key OpenRouter disimpan di frontend, mobile app, atau JavaScript browser, key tersebut pada praktiknya dianggap publik. Obfuscation tidak cukup karena request tetap dapat diinspeksi.

Mitigasi: simpan key hanya di server, idealnya di secret manager. Gateway menjadi satu-satunya komponen yang dapat mengakses key tersebut.

2. Abuse oleh user terautentikasi

Masalah bukan hanya attacker anonim. User valid juga bisa mengirim prompt sangat besar, melakukan spam request paralel, atau mengeksploitasi endpoint untuk menaikkan biaya.

Mitigasi: rate limit per user, kuota harian/bulanan, batas payload, dan policy parameter yang ketat.

3. Abuse dari IP anonim atau bot

Walau user auth sudah diterapkan, endpoint publik tetap bisa dibanjiri request acak, terutama endpoint login, session refresh, atau route AI yang terekspos ke internet.

Mitigasi: rate limit per IP, proteksi burst traffic, WAF/CDN bila perlu, dan timeout yang masuk akal.

4. Replay request

Request yang sah dapat direkam lalu dikirim ulang berkali-kali untuk memperbanyak konsumsi resource atau biaya.

Mitigasi: gunakan idempotency key, nonce, timestamp, dan masa berlaku request yang pendek untuk operasi sensitif.

5. Logging yang membocorkan data sensitif

Developer sering tidak sengaja menulis header Authorization, payload mentah, atau respons upstream penuh ke log.

Mitigasi: redaksi secret, hashing identifier tertentu, dan logging hanya field yang diperlukan untuk audit/debug.

6. Error upstream yang diteruskan mentah

Meneruskan pesan error mentah dari upstream bisa membocorkan detail internal, struktur request, atau alasan penolakan yang seharusnya tidak diketahui klien.

Mitigasi: lakukan normalisasi error dan bedakan antara detail internal untuk log dengan pesan aman untuk klien.

Auth dan Pemisahan Secret Secara Server-Side

Jangan gunakan API key OpenRouter sebagai kredensial klien

Klien seharusnya hanya mengetahui token milik sistem Anda sendiri, misalnya session cookie HttpOnly, JWT internal, atau access token opaque. Gateway kemudian memetakan identitas ini ke policy internal dan baru setelah itu menambahkan API key upstream.

Dengan model ini, Anda mendapat beberapa keuntungan:

API key upstream bisa diganti tanpa memengaruhi klien.
Hak akses bisa dibedakan per user, tenant, atau plan.
Request dapat dicabut, dibatasi, atau diaudit per identitas internal.
Jika satu token klien bocor, Anda tidak perlu merotasi key upstream global.

Session-to-token mapping

Pola yang aman adalah memisahkan identitas user dari kredensial upstream. User login ke sistem Anda, lalu gateway membuat keputusan berikut saat menerima request:

siapa user atau service ini,
tenant mana yang dimiliki,
route/model/policy apa yang boleh dipakai,
berapa limit per menit/per jam,
apakah request perlu idempotency key atau approval tambahan.

Gateway tidak perlu membuat satu API key upstream per user. Yang lebih penting adalah pemetaan policy internal ke satu atau beberapa secret server-side. Pada sistem multi-tenant, Anda bisa menambahkan routing secret berdasarkan tenant, lingkungan, atau jenis workload.

Penyimpanan secret yang benar

Pilihan terbaik adalah secret manager atau mekanisme injeksi secret di runtime. Jika belum tersedia, minimal gunakan environment variable pada server dengan kontrol akses ketat. Hindari:

menaruh secret di repository,
menyimpan secret dalam file konfigurasi yang ikut dibuild ke image tanpa kontrol rotasi,
mencetak secret ke log saat startup atau error,
mengirim secret ke frontend untuk "memudahkan debugging".

Rotasi secret

Rotasi secret sebaiknya didesain sejak awal, bukan setelah insiden. Pola yang umum dipakai adalah dual-key rotation:

Simpan active secret dan next secret di secret store.
Gateway dapat membaca keduanya selama masa transisi.
Gunakan secret baru untuk request baru, tetapi pertahankan kompatibilitas untuk request yang masih in-flight jika arsitektur Anda membutuhkannya.
Setelah semua node memuat secret baru dan validasi selesai, nonaktifkan secret lama.

Jika aplikasi Anda melakukan cache secret di memori, pastikan ada strategi reload atau restart terkontrol. Kesalahan umum adalah secret sudah diganti di secret store, tetapi proses aplikasi masih memakai nilai lama karena cache tidak pernah disegarkan.

Validasi Input dan Pembatasan Payload

Gateway aman tidak boleh sekadar menjadi pass-through proxy. Ia harus memeriksa apakah payload masuk sesuai ekspektasi sebelum diteruskan ke OpenRouter Fusion API.

Validasi field dan whitelist parameter

Jangan teruskan semua field yang dikirim klien. Terapkan allowlist untuk field yang memang Anda dukung. Ini mengurangi risiko penyalahgunaan parameter eksperimen, field tak dikenal, atau input yang memperbesar biaya.

Contoh yang sebaiknya divalidasi:

field wajib ada dan bertipe benar,
nilai numerik berada pada rentang aman,
parameter string tidak kosong dan punya batas panjang,
field yang tidak didukung ditolak atau diabaikan secara eksplisit.

Batas ukuran payload

Payload besar bisa menjadi sumber biaya, latensi, dan serangan denial-of-service. Terapkan beberapa lapisan batas:

Maximum request body size di reverse proxy dan aplikasi.
Batas panjang prompt atau jumlah item pada array tertentu.
Batas jumlah attachment/metadata jika endpoint mendukung input tambahan.

Pastikan klien menerima status yang jelas, misalnya 413 Payload Too Large untuk body terlalu besar, atau 422 Unprocessable Entity untuk field valid secara sintaks tetapi melanggar policy aplikasi.

Sanitasi prompt: apa yang realistis?

Validasi prompt tidak berarti Anda bisa sepenuhnya "membersihkan" isi prompt seperti sanitasi HTML pada aplikasi web. Untuk konteks LLM, pendekatan yang realistis adalah:

batasi panjang input,
blokir pola yang jelas-jelas tidak relevan dengan use case jika memang diperlukan,
pisahkan system instruction internal dari input user,
jangan izinkan klien mengatur parameter yang seharusnya menjadi policy server.

Kesalahan umum adalah menganggap filter kata kunci sederhana cukup untuk keamanan. Pada praktiknya, kontrol paling efektif justru datang dari pembatasan parameter, kuota, logging, dan segregasi hak akses.

Rate Limit, Burst Control, dan Proteksi Replay

Rate limit per user dan per IP

Gunakan minimal dua dimensi rate limit:

Per user/session/token internal untuk mencegah satu akun menghabiskan resource.
Per IP untuk menahan trafik anonim, bot, atau abuse sebelum auth.

Per user melindungi biaya dan fairness. Per IP melindungi ketersediaan layanan. Keduanya tidak saling menggantikan.

Algoritma rate limit

Untuk banyak sistem, token bucket atau sliding window adalah pilihan praktis.

Token bucket cocok jika Anda ingin mengizinkan burst kecil tetapi tetap menjaga rata-rata trafik.
Sliding window lebih mudah dipahami untuk kebijakan seperti "N request per menit" namun implementasinya perlu hati-hati agar akurat di sistem terdistribusi.

Jika beban tersebar ke banyak instance, simpan counter di store terpusat seperti Redis agar limit konsisten.

Proteksi burst traffic

Rate limit standar kadang masih terlalu longgar terhadap lonjakan singkat. Karena itu, tambahkan kontrol burst seperti:

batas konkurensi per user,
queue pendek dengan timeout,
circuit breaker untuk upstream lambat,
reject cepat saat sistem melewati ambang tertentu.

Ini penting agar antrean internal tidak tumbuh tanpa batas ketika upstream melambat atau saat terjadi spike mendadak.

Replay protection

Untuk request yang berpotensi mahal atau tidak boleh diproses berulang, minta klien mengirim Idempotency-Key atau nonce unik. Gateway lalu menyimpan jejak kunci tersebut untuk waktu tertentu.

Skema praktis:

klien mengirim timestamp dan idempotency key,
gateway menolak request yang timestamp-nya terlalu lama atau terlalu jauh di masa depan,
gateway menolak key yang sudah pernah dipakai untuk payload yang sama atau berbeda sesuai policy Anda.

Trade-off-nya adalah Anda butuh storage tambahan dan kebijakan retensi. Namun ini jauh lebih aman untuk endpoint berbiaya tinggi.

Audit Logging yang Aman

Logging diperlukan untuk audit, billing, dan debugging. Tetapi tanpa redaksi, log justru menjadi sumber kebocoran paling besar.

Apa yang sebaiknya dicatat

timestamp, request ID, correlation ID, user ID/tenant ID, IP, route, hasil rate limit, status code, latensi, ukuran payload, dan upstream status.
hash atau ringkasan pendek dari prompt jika memang perlu korelasi.
jenis error yang dinormalisasi, bukan dump mentah seluruh respons.

Apa yang tidak boleh dicatat

header Authorization, API key, session token, cookie.
payload penuh yang mengandung data sensitif kecuali benar-benar diperlukan dan diatur oleh kebijakan privasi yang jelas.
respons upstream mentah yang mungkin memuat informasi sensitif atau internal.

Catatan: jika Anda perlu merekam payload untuk investigasi insiden, buat jalur logging terpisah dengan akses sangat terbatas, retensi pendek, dan redaksi otomatis.

Correlation ID

Setiap request sebaiknya memiliki request ID unik. ID ini dibawa dari gateway ke downstream log internal agar debugging tidak bergantung pada data sensitif. Jika upstream mendukung header tambahan yang aman untuk korelasi, gunakan nilai yang sama atau turunan darinya.

Penanganan Error Upstream yang Aman

Ketika OpenRouter Fusion API mengembalikan error, gateway tidak perlu meneruskan detail mentah ke klien. Gunakan dua lapisan informasi:

Pesan aman untuk klien: singkat, konsisten, tanpa detail internal.
Detail lengkap untuk log internal: termasuk upstream status, timeout, kategori error, dan request ID.

Pemetaan error yang disarankan

400/422 dari gateway untuk payload klien yang tidak lolos validasi internal.
401/403 untuk auth atau policy internal yang gagal.
429 untuk rate limit lokal gateway.
502 saat upstream memberi respons tidak valid atau gagal diproses dengan benar.
503 saat upstream tidak tersedia atau circuit breaker aktif.
504 saat timeout ke upstream.

Hindari mengembalikan pesan seperti "API key invalid" atau body error upstream mentah, karena itu membuka detail operasional yang tidak perlu diketahui klien.

Timeout dan retry

Retry otomatis tidak selalu aman. Untuk request yang mahal atau tidak idempoten, retry buta bisa memperburuk biaya dan duplikasi proses. Gunakan retry hanya jika:

jenis error memang transien,
operasi aman untuk diulang,
ada idempotency key atau mekanisme deduplikasi.

Selalu tetapkan timeout outbound yang jelas. Tanpa timeout, koneksi bisa menggantung dan menghabiskan worker/thread hingga layanan Anda ikut lumpuh.

Contoh Pseudocode Middleware Backend

Berikut contoh pseudocode yang menggambarkan urutan kontrol pada gateway. Sintaksnya sengaja dibuat generik agar bisa diadaptasi ke Express, FastAPI, Go, Laravel, atau framework lain.

function handleAiGenerate(request) {
  const requestId = ensureRequestId(request)
  const clientIp = getTrustedClientIp(request)

  try {
    enforceContentTypeJson(request)
    enforceMaxBodySize(request, MAX_BODY_BYTES)

    const session = authenticateClient(request)
    if (!session) {
      return response(401, { error: "unauthorized", request_id: requestId })
    }

    const user = loadUserPolicy(session.userId)
    if (!user || !user.aiAccessEnabled) {
      return response(403, { error: "forbidden", request_id: requestId })
    }

    const idempotencyKey = request.header("Idempotency-Key")
    const clientTimestamp = request.header("X-Request-Timestamp")
    validateFreshTimestamp(clientTimestamp, MAX_CLOCK_SKEW_MS)
    ensureReplaySafe(session.userId, idempotencyKey, clientTimestamp)

    applyRateLimit({
      key: "ip:" + clientIp,
      limit: IP_LIMIT,
      window: "1m"
    })

    applyRateLimit({
      key: "user:" + session.userId,
      limit: user.perMinuteLimit,
      window: "1m"
    })

    enforceConcurrencyLimit("user:" + session.userId, user.maxConcurrentRequests)

    const body = parseJson(request.body)
    const sanitized = validateAndNormalizePayload(body, {
      allowedFields: ["model", "messages", "temperature", "max_tokens"],
      maxPromptChars: user.maxPromptChars,
      maxMessages: user.maxMessages,
      allowedModels: user.allowedModels
    })

    const upstreamSecret = secretManager.get("OPENROUTER_FUSION_API_KEY_ACTIVE")
    const upstreamRequest = {
      method: "POST",
      url: OPENROUTER_FUSION_URL,
      headers: {
        "Authorization": "Bearer " + upstreamSecret,
        "Content-Type": "application/json",
        "X-Request-Id": requestId
      },
      body: sanitized,
      timeoutMs: UPSTREAM_TIMEOUT_MS
    }

    const upstreamResponse = httpClient.send(upstreamRequest)
    const safeBody = normalizeUpstreamResponse(upstreamResponse)

    auditLog({
      requestId,
      userId: session.userId,
      tenantId: session.tenantId,
      ip: clientIp,
      route: "/ai/generate",
      status: upstreamResponse.status,
      payloadBytes: request.body.length,
      model: sanitized.model
    })

    return response(upstreamResponse.status, safeBody)
  } catch (err) {
    const mapped = mapErrorToSafeResponse(err)

    auditLog({
      requestId,
      ip: clientIp,
      route: "/ai/generate",
      errorType: mapped.internalCode,
      status: mapped.status
    })

    return response(mapped.status, {
      error: mapped.publicMessage,
      request_id: requestId
    })
  } finally {
    releaseConcurrencySlotIfAny(request)
  }
}

Yang penting dari contoh di atas bukan nama fungsinya, melainkan urutannya: auth dulu, policy dan rate limit, validasi payload, baru forward ke upstream. Banyak implementasi terbalik: request sudah diparsing dan diproses berat lebih dulu sebelum auth dan limit diperiksa.

Checklist Implementasi Produksi

Klien tidak pernah menerima API key upstream.
Session atau token internal diverifikasi di gateway.
Secret disimpan di secret manager atau environment yang terkendali.
Rotasi secret didukung tanpa deploy darurat besar-besaran.
Whitelist field request dan batasi parameter yang didukung.
Body size limit diterapkan di reverse proxy dan aplikasi.
Prompt/message length dibatasi sesuai policy.
Rate limit per user dan per IP aktif.
Concurrency limit atau burst control aktif.
Replay protection menggunakan idempotency key atau nonce untuk endpoint mahal.
Timeout outbound ke upstream dikonfigurasi.
Error upstream dinormalisasi sebelum dikirim ke klien.
Authorization header, cookie, dan secret di-redact dari log.
Request ID/correlation ID tersedia di semua log.
Monitoring dan alert untuk lonjakan 429, 5xx, dan timeout tersedia.

Kesalahan Umum dan Tips Debugging

Kesalahan umum

Mengandalkan frontend untuk pembatasan input. Semua pembatasan penting harus ditegakkan ulang di server.
Mencatat body request penuh secara default. Ini sering menjadi sumber kebocoran pertama.
Hanya memasang rate limit per IP. User terautentikasi masih bisa menyalahgunakan endpoint dari satu IP yang sah.
Tidak memikirkan timeout dan concurrency. Upstream lambat bisa membuat worker habis walau CPU rendah.
Rotasi secret tidak pernah diuji. Saat insiden terjadi, proses rotasi justru gagal karena belum pernah dipraktikkan.

Tips debugging

Jika banyak 429, cek apakah limit per user dan per IP saling bertabrakan terlalu ketat.
Jika respons sering 504, periksa timeout outbound, antrean internal, dan konkurensi request.
Jika request valid ditolak sebagai replay, cek sinkronisasi waktu antar node dan toleransi clock skew.
Jika setelah rotasi secret request mulai gagal, pastikan semua instance memuat secret baru dan tidak ada cache yang stale.
Gunakan request ID untuk menelusuri satu transaksi dari edge, gateway, hingga log upstream internal.

Penutup

Mengamankan integrasi dengan OpenRouter Fusion API bukan soal menyembunyikan satu API key saja. Di produksi, Anda memerlukan gateway yang berfungsi sebagai lapisan kontrol: autentikasi internal, isolasi secret, validasi payload, rate limit per user dan per IP, proteksi replay, audit logging aman, serta penanganan error upstream yang tidak membocorkan detail sensitif.

Jika Anda baru memulai, urutan prioritas yang paling masuk akal adalah: pindahkan key ke server-side, pasang auth internal, terapkan body/prompt limit, tambahkan rate limit, lalu rapikan logging dan rotasi secret. Dengan urutan itu, Anda menutup risiko terbesar lebih dulu tanpa membuat arsitektur terlalu rumit sejak awal.

Quick Search

shopping_cart Keranjang