Autentikasi & Peran

Ikhtisar

Private Channels menyertakan Auth Service opsional yang membatasi akses gateway dengan autentikasi JWT dan kontrol akses berbasis peran (RBAC). Ketika autentikasi dinonaktifkan, gateway menerima semua koneksi. Ketika diaktifkan, klien harus menyertakan JWT yang valid di setiap permintaan.

Halaman ini mencakup kedua audiens:

• Developer - registrasi, login, verifikasi wallet, dan membuat permintaan terautentikasi
• Operator - mengaktifkan auth service, mengonfigurasi JWT_SECRET, dan menyediakan peran operator

Mengaktifkan Auth

Autentikasi diaktifkan dengan menetapkan JWT_SECRET (tidak kosong) pada gateway maupun Auth Service. Auth Service juga memerlukan AUTH_DATABASE_URL.

Ketika JWT_SECRET tidak disetel, gateway beroperasi dalam mode terbuka; tidak ada token yang diperlukan.

Docker Compose: Auth service adalah profil Docker Compose dan tidak dimulai secara default. Untuk menyertakannya, tambahkan --profile auth pada perintah docker compose Anda, termasuk --env-file .env agar secrets seperti JWT_SECRET dan POSTGRES_PASSWORD dapat terselesaikan (Compose menonaktifkan pemuatan otomatis .env setelah flag --env-file apa pun digunakan):

docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet --env-file .env --profile auth up -d

API Auth Service

Semua endpoint berada di bawah /auth. Auth service mendengarkan pada AUTH_PORT (default 8903).

POST /auth/register

Membuat akun baru. Semua pengguna didaftarkan dengan peran user.

{ "username": "alice", "password": "hunter2" }

• Username: 5-32 karakter, alfanumerik ditambah _ dan -
• Password: 6-128 karakter
• Mengembalikan pengguna yang dibuat; password tidak pernah dikembalikan

POST /auth/login

Autentikasi dan terima JWT bertanda tangan yang berlaku selama 24 jam.

{ "username": "alice", "password": "hunter2" }

Mengembalikan { "token": "<jwt>" }. Username salah maupun password salah keduanya mengembalikan 401 untuk mencegah enumerasi username.

POST /auth/challenge-wallet

Meminta tantangan penandatanganan untuk membuktikan kepemilikan wallet Solana. Memerlukan JWT yang valid.

Mengembalikan pesan, nonce, dan waktu kedaluwarsa. Tantangan kedaluwarsa dalam 10 menit.

{
  "message": "PrivateChannel wallet verification\nuser: <uuid>\nnonce: <uuid>\nexpires: <unix>",
  "nonce": "<uuid>",
  "expires_at": "<iso8601>"
}

POST /auth/verify-wallet

Mengirimkan tantangan yang telah ditandatangani untuk mendaftarkan wallet sebagai terverifikasi. Memerlukan JWT yang valid.

{
  "pubkey": "<base58 pubkey>",
  "nonce": "<uuid from challenge>",
  "signature": "<base58 Ed25519 signature>"
}

Layanan merekonstruksi pesan tantangan, memverifikasi tanda tangan Ed25519, dan menyimpan wallet. Setiap nonce hanya dapat dikonsumsi satu kali; replay akan ditolak.

Mengembalikan { "pubkey": "<base58>", "created_at": "<iso8601>" }.

GET /auth/wallets

Menampilkan semua wallet terverifikasi untuk pengguna yang terautentikasi. Memerlukan JWT yang valid.

DELETE /auth/wallets/{pubkey}

Menghapus wallet terverifikasi dari akun pengguna yang terautentikasi. Memerlukan JWT yang valid.

GET /health

Pemeriksaan liveness. Mengembalikan 200 ok. Tidak memerlukan autentikasi.

Struktur JWT

Token menggunakan algoritma HS256 dan kedaluwarsa 24 jam setelah diterbitkan.

iss dan aud hadir dalam payload JWT tetapi divalidasi oleh konfigurasi JWT gateway, bukan dideserialisasi ke dalam struct klaim aplikasi. Kode lapisan aplikasi hanya memiliki akses ke sub, role, dan exp.

Kirimkan token di header Authorization:

Authorization: Bearer <JWT_TOKEN>

Peran

user

Peran default saat registrasi.

• Akses dibatasi pada wallet terverifikasi milik pengguna itu sendiri
• Diblokir dari: getBlock, getTransaction, simulateTransaction
• Dapat: memanggil Deposit pada Escrow Program, memulai penarikan melalui WithdrawFunds

operator

Peran yang ditingkatkan. Harus disediakan secara langsung; tidak ada jalur mandiri untuk naik dari user ke operator.

Berikan peran, baik melalui Admin CLI (private-channel-auth-admin):

private-channel-auth-admin set-role --username alice --role operator

atau dengan SQL langsung:

UPDATE private_channel_auth.users SET role = 'operator' WHERE username = 'alice';

Daftarkan wallet tanpa alur self-verify (Admin CLI, private-channel-auth-admin):

private-channel-auth-admin attach-wallet --username alice --pubkey <base58-pubkey>

Perintah ini menyisipkan wallet terverifikasi langsung ke tabel verified_wallets, melewati alur challenge/verify. Menerapkan batasan unik pada (user_id, pubkey). Perintah ini tidak memberikan peran operator dengan sendirinya; gunakan set-role atau pembaruan SQL di atas untuk itu. Perintah ini digunakan untuk melampirkan wallet ke akun (misalnya, akun layanan) tanpa memerlukan alur challenge/verify interaktif.

Kemampuan:

• Melewati semua pemeriksaan kepemilikan wallet
• Akses penuh ke semua metode RPC gateway, termasuk getBlock, getTransaction, simulateTransaction
• Diperlukan untuk: ReleaseFunds, ResetSmtRoot

Alur Autentikasi Lengkap

Membuat Permintaan Terautentikasi

const response = await fetch("http://localhost:8899/", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${jwtToken}`
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "getBalance",
    params: [walletAddress]
  })
});
const data = await response.json();

Endpoint Gateway

Endpoint berikut tidak memerlukan autentikasi:

Untuk referensi JWT_SECRET dan variabel lingkungan gateway, lihat Referensi Konfigurasi.

Matriks Akses Metode RPC

Metode berikut dikenali oleh gateway. Ketika JWT_SECRET disetel, akses bergantung pada peran JWT:

¹ Ownership-gated: untuk SPL Token account (field owner adalah TokenkegQ... atau TokenzQ..., data minimal 165 byte), gateway memeriksa bahwa field owner atau delegate cocok dengan salah satu wallet terverifikasi milik pengguna yang terautentikasi. Untuk tipe akun lainnya (wallet System Program, atau PDA yang tidak dikenal), gateway memeriksa apakah pubkey yang diminta itu sendiri merupakan salah satu wallet terverifikasi milik pengguna, karena akun semacam itu tidak memiliki field owner/delegate untuk diperiksa. Jika salah satu pemeriksaan gagal, akan mengembalikan 403.