---
title: "Arsitektur, model ancaman, detail protokol proxy kredensial"
description: "Cara kerja proxy kredensial Clavitor pada tingkat protokol. MITM TLS, siklus hidup kredensial, kode kesalahan, perlindungan SSRF, dan apa yang tidak dilindunginya."
lang: id
url: https://clavitor.ai/id/proxy-technical
markdown: https://clavitor.ai/id/proxy-technical.md
translation_of: https://clavitor.ai/en/proxy-technical.md
authoritative: false
publisher: Clavitor LLC
---

> This is the Indonesian translation of [Credential Proxy Technical — Architecture, threat model, protocol details](https://clavitor.ai/en/proxy-technical.md). The original English text is authoritative; where the two differ, the English version prevails.

# Proxy kredensial — teknis: Cara kerja proxy.

Apa yang dilindunginya. Apa yang tidak.
Halaman ini ditujukan untuk peninjau keamanan, penguji penetrasi, dan insinyur yang mengevaluasi model ancaman proxy. Halaman ini menjelaskan apa yang dilakukan proxy pada tingkat protokol, di mana kredensial ada di memori, dan permukaan serangan apa yang tersisa.

## Arsitektur

Proxy adalah proxy HTTPS MITM berbasis CONNECT. Agen AI mengatur `HTTPS_PROXY` untuk mengarah padanya. Ketika agen membuat permintaan HTTPS, proxy mencegat koneksi TLS, memeriksa header permintaan untuk referensi kredensial, menyelesaikannya terhadap brankas Clavitor, dan meneruskan permintaan dengan kredensial yang disuntikkan ke API hulu.

Proxy mendengarkan pada `127.0.0.1:1983` secara default — pola sidecar di mana proxy dan agen berbagi host. Untuk penyebaran bersama (satu proxy melayani banyak agen di jaringan pribadi, sidecar kontainer ke banyak beban kerja, host proxy khusus), antarmuka pendengar dapat dikonfigurasi melalui `CLAVITOR_PROXY_LISTEN`.

Proxy adalah biner Go mandiri. Tanpa CGO. Seluruh kriptografi protokol Clavitor diproses melalui implementasi Rust kanonik yang dikompilasi ke WebAssembly dan dimuat melalui wazero saat startup.

## Penanganan TLS

Proxy menghasilkan CA root ECDSA P-256 yang ditandatangani sendiri saat pertama kali dijalankan, disimpan di direktori biner dengan mode `0600`. Untuk setiap host hulu, sertifikat leaf diterbitkan sesuai permintaan, ditandatangani oleh CA ini, dan di-cache dalam memori dengan eviksi terbatas (1.000 host). Sertifikat leaf berlaku selama 24 jam dan dibuat ulang secara transparan pada jam ke-23 untuk mencegah kedaluwarsa di tengah sesi.

Agen harus mempercayai sertifikat CA proxy. Ekspor dengan `clavitor-proxy ca`.

Koneksi hulu menggunakan TLS 1.3 minimum dengan negosiasi ALPN untuk HTTP/2 dan HTTP/1.1. Kumpulan sertifikat sistem digunakan untuk verifikasi hulu. Tidak ada penyematan sertifikat — proxy mempercayai apa pun yang dipercayai OS.

## Credential lifecycle

Kredensial tidak pernah di-cache, tidak pernah ditulis ke disk, dan tidak pernah disimpan lebih lama dari satu permintaan HTTP.

| Fase | Di mana kredensial berada | Durasi |
|-------|----------------------------|----------|
| Saat diam di brankas | Ciphertext AES-GCM di database brankas | Hingga dihapus |
| Dalam transit ke proxy | Respons JSON terenkripsi TLS dari API brankas | Satu putaran HTTP |
| Didekripsi di proxy | Memori proses (string Go di heap) | Satu permintaan HTTP |
| Disuntikkan ke dalam permintaan hulu | Byte terenkripsi TLS di jalur ke hulu | Satu permintaan HTTP |

Proxy menyimpan kunci dekripsi kredensial agen (16 byte) dalam memori selama seluruh waktu berjalan. Kunci dimuat dari konfigurasi sidecar terenkripsi (format CLV1) saat startup dan dihapus saat shutdown yang terkendali. Kunci tidak pernah meninggalkan proses.

Konfigurasi sidecar dienkripsi dengan AES-128-GCM dan HMAC-SHA256 menggunakan kunci deterministik yang diturunkan dari seed statis. Ini adalah obfuskasi, bukan kerahasiaan — batas keamanan adalah izin file (`0600`) dan kepemilikan file. Format CLV1 dibagikan antara proxy, CLI, dan ekstensi peramban.

## Mode resolusi

### Mode 1 — placeholder eksplisit

Agen menyertakan referensi `clavitor://Entry/field` dalam header permintaan. Proxy mencari entri di brankas berdasarkan nama, mengambilnya, mendekripsi bidang yang disebutkan, dan mengganti placeholder dengan nilai sebenarnya.

Jika pencarian mengembalikan nol atau lebih dari satu hasil, proxy mengembalikan `502` dengan kode kesalahan yang stabil. Placeholder **tidak pernah** dihapus dan diteruskan apa adanya.

### Mode 2 — pencocokan URL

Ketika tidak ada placeholder, proxy meminta brankas untuk entri yang bidang URL-nya cocok dengan host hulu. Jika tepat satu kecocokan ada dengan bentuk bidang yang dikenali, proxy menyuntikkan kredensial secara otomatis.

Nol kecocokan → passthrough (tidak ada ekspektasi kredensial). Banyak kecocokan → `502` dengan panduan klarifikasi. Bentuk bidang tidak diketahui → `502`.

Pohon keputusan bersifat deterministik: placeholder ada → selesaikan atau gagal. Tidak ada placeholder → pencocokan URL atau passthrough. Tidak ada jalur fallback tersembunyi di mana resolusi yang gagal menghasilkan permintaan yang diteruskan ke hulu tanpa kredensial.

## Agent identity

Secara default, brankas melihat ID agen proxy sendiri pada setiap permintaan. Batas laju, pemeriksaan cakupan, dan entri audit dikaitkan dengan proxy.

Ketika banyak agen berbagi satu instance proxy, placeholder dapat menyertakan ID agen: `clavitor://agentid@Entry/field`. Proxy mengirimkan ID agen ini ke brankas, yang menerapkan cakupan agen tersebut dan batas laju serta mencatat akses terhadapnya. ID agen adalah nilai heksadesimal 32 karakter yang ditampilkan di halaman detail agen di UI brankas.

```
# Without agent ID — attributed to the proxy

Authorization: Bearer clavitor://OpenAI/key

# With agent ID — attributed to agent 0102030405060708090a0b0c0d0e0f10

Authorization: Bearer clavitor://0102030405060708090a0b0c0d0e0f10@OpenAI/key
```

| Penyebaran | Model identitas | Isolasi |
|------------|----------------|-----------|
| Satu proxy per agen | ID Proxy = ID agen (default) | Penuh — biner, konfigurasi, cakupan, batas laju terpisah |
| Proxy bersama, tanpa ID agen di URL | Semua agen berbagi ID proxy | Cakupan dan batas laju bersama |
| Proxy bersama + `agentid@` di URL | Identitas per agen | Cakupan, batas laju, dan audit per agen |

ID agen di URL bukanlah mekanisme otentikasi — token CVT proxy mengotentikasi koneksi. ID agen menentukan atribusi: cakupan siapa yang berlaku, batas laju siapa yang dihitung, jejak audit siapa yang mencatat akses. Brankas menolak ID agen yang tidak dikenal dengan kegagalan yang eksplisit.

## Keamanan jaringan

### Perlindungan SSRF

Secara default, proxy memblokir koneksi hulu ke jaringan pribadi (RFC 1918), metadata instance cloud (`169.254.169.254`), loopback, link-local, dan rentang NAT kelas operator. DNS diselesaikan terlebih dahulu; semua IP yang dikembalikan divalidasi sebelum koneksi TCP dibuat, menutup jendela TOCTOU rebinding DNS.

Timpa dengan `CLAVITOR_PROXY_ALLOW_PRIVATE=true` untuk agen yang sah mengakses API pribadi.

### Penyematan target

Target CONNECT ditangkap saat pembentukan terowongan dan digunakan untuk seluruh masa pakai terowongan. Permintaan selanjutnya dalam terowongan tidak dapat mengalihkan ke host yang berbeda dengan memanipulasi header `Host`. Ketidakcocokan menghasilkan `502`.

Ini mencegah agen membuat terowongan ke `api.openai.com` dan kemudian mengirim permintaan ke `internal-service.corp`.

## Penanganan header

Header hop-by-hop dihapus dari permintaan dan respons sesuai RFC 7230 §6.1: `Connection`, `Keep-Alive`, `Proxy-Authenticate`, `Proxy-Authorization`, `Proxy-Connection`, `TE`, `Trailers`, `Transfer-Encoding`, `Upgrade`.

`Set-Cookie` dihapus dari respons hulu untuk mencegah hulu menanam cookie di klien HTTP agen.

Badan permintaan dan respons dialirkan tanpa buffering. Badan permintaan dibatasi hingga 64 MB secara default (`CLAVITOR_PROXY_MAX_BODY_MB`). Badan respons dialirkan tanpa batas keras; peringatan log dikeluarkan ketika `Content-Length` melebihi 100 MB.

## Field-to-header mapping

Dalam mode pencocokan URL, proxy memetakan label bidang brankas ke header HTTP:

| Label bidang | Header yang disuntikkan |
|-------------|-----------------|
| `key`, `apikey`, `api_key`, `token`, `secret`, `bearer`, `access_token` | `Authorization: Bearer <value>` |
| `x-api-key`, `api-key` | `X-API-Key: <value>` |
| `username` + `password` (berpasangan) | `Authorization: Basic base64(user:pass)` |
| Apa pun yang lain | Ditolak — `ERR-PROXY-052` |

Dalam mode placeholder, agen mengontrol bidang mana yang diselesaikan dan ke mana tujuannya. Pemetaan di atas hanya berlaku untuk mode pencocokan URL.

## Error codes

Setiap kegagalan menghasilkan kode `ERR-PROXY-NNN` yang stabil. Kode-kode ini adalah bagian dari antarmuka publik proxy — agen dan operator dapat mencocokkannya untuk peringatan dan debugging.

| Rentang | Kategori |
|-------|----------|
| `001–019` | Pengaturan (konfigurasi, inisialisasi, pembuatan CA, WASM) |
| `020–029` | Siklus hidup daemon |
| `030–049` | Resolusi placeholder (URI `clavitor://`) |
| `050–069` | Injeksi pencocokan URL |
| `070–089` | Hulu / TLS |

## Bidang identitas tidak dapat dijangkau

Entri brankas mendukung tiga tingkatan enkripsi. Bidang Enkripsi brankas adalah metadata plaintext. Bidang Enkripsi kredensial didekripsi dengan kunci agen. Bidang Enkripsi identitas dienkripsi dengan kunci yang belum pernah dilihat oleh server dan proxy. Hanya pemilik brankas, melalui kunci perangkat kerasnya, yang dapat mendekripsinya.

Jika placeholder merujuk ke bidang Enkripsi identitas, proxy mengembalikan `ERR-PROXY-035`. Tidak ada fallback, tidak ada hasil parsial. Bidang tersebut secara arsitektural tidak dapat dijangkau dari proxy.

## Apa yang tidak dilindungi oleh proxy

Model ancaman proxy adalah **keterampilan yang disusupi atau injeksi prompt yang membuat agen yang terautentikasi memanen kredensial**. Batas laju per agen brankas, kuota entri unik, dan penguncian dua kali percobaan adalah pertahanan utama. Proxy menambahkan titik penegakan lapisan jaringan di mana kredensial diselesaikan per permintaan dan tidak pernah disimpan oleh agen.

### Host yang disusupi

Proxy berjalan di mesin yang sama dengan agen. Penyerang dengan akses root dapat membaca memori proses, melampirkan debugger, atau mencegat lalu lintas loopback. Proxy adalah lapisan injeksi kredensial, bukan batas keamanan perangkat keras.

### Eksfiltrasi kredensial melalui respons API

Jika API hulu menggemakan kredensial kembali dalam responsnya (misalnya, titik akhir "whoami"), agen akan melihatnya. Proxy menyuntikkan kredensial ke dalam permintaan, bukan respons. Proxy tidak memfilter apa yang kembali.

## Pencatatan

Proxy mencatat satu baris per CONNECT yang diterima dan mengeluarkan baris kesalahan untuk kegagalan. Proxy **tidak pernah** mencatat:

- Nilai kredensial yang didekripsi
- URL permintaan lengkap (string kueri dapat membawa rahasia — hanya skema + host + jalur yang dicatat)
- Badan permintaan atau respons
- Kunci dekripsi kredensial atau isi konfigurasi sidecar

Ketika proxy mendeteksi bahwa respons 400 dari hulu berisi kata kunci terkait otentikasi (`unauthorized`, `invalid token`, dll.), ia mencatat petunjuk diagnostik yang menunjukkan kredensial yang disuntikkan mungkin sudah usang. Respons diteruskan tanpa perubahan.

## Kriptografi

Semua kriptografi protokol Clavitor — dekripsi bidang AES-GCM, derivasi kunci HKDF, pengkodean base62, penerbitan token CVT, pengemasan/pembongkaran paket konfigurasi CLV1 — dieksekusi di dalam satu modul WebAssembly (`clavis_crypto.wasm`) yang dimuat melalui [wazero](https://wazero.io), runtime WASM murni Go. Tanpa CGO. Tanpa implementasi ulang primitif Clavitor oleh Go.

Modul WASM dikompilasi dari crate Rust yang sama (`clavis-crypto`) yang digunakan oleh peramban, CLI, dan ekstensi peramban. Satu sumber kebenaran, satu biner, satu permukaan audit.

Proxy menggunakan `crypto/tls` Go untuk TLS di jalur dan `crypto/ecdsa` untuk pembuatan sertifikat MITM. Ini adalah masalah transportasi, bukan operasi protokol Clavitor.

## Configuration

Rahasia (kunci dekripsi kredensial, ID agen, ID perangkat, URL brankas) berada di konfigurasi sidecar CLV1 terenkripsi, ditulis sekali selama `clavitor-proxy init`. Parameter operasional berada di variabel lingkungan:

| Variabel | Default | Tujuan |
|----------|---------|---------|
| `CLAVITOR_PROXY_LISTEN` | `127.0.0.1` | Antarmuka pendengar. Atur ke `0.0.0.0` untuk penyebaran bersama, atau ke IP antarmuka tertentu. |
| `CLAVITOR_PROXY_PORT` | `1983` | Port pendengar |
| `CLAVITOR_PROXY_ALLOW_PRIVATE` | `false` | Izinkan koneksi ke jaringan RFC-1918 / pribadi |
| `CLAVITOR_PROXY_MAX_BODY_MB` | `64` | Batas ukuran badan permintaan |
| `CLAVITOR_PROXY_WRITE_TIMEOUT` | `300` | Waktu tunggu penulisan respons dalam detik |
| `CLAVITOR_CONFIG` | *(direktori exe)* | Timpa jalur konfigurasi sidecar |

Parameter operasional bukanlah rahasia. Mereka tidak termasuk dalam konfigurasi terenkripsi. Mereka berada di tempat alat penyebaran sudah mengelolanya — lingkungan.

## Tinjau sendiri.

Kriptografi adalah satu artefak WASM yang dapat diaudit. Model ancaman didokumentasikan. Jika Anda menemukan sesuatu yang kami lewatkan, kami ingin mendengarnya.
[Laporkan temuan](mailto:security@clavitor.ai)
[← Tinjauan bisnis](https://clavitor.ai/id/proxy)