Core Module

Dokumentasi ringkas untuk modul inti TrueDignity. Bagian ini memuat gambaran umum fitur inti, alur kerja dasar, dan referensi teknis tingkat tinggi.

Arsitektur Perangkat Lunak

Sistem ini terdiri dari empat domain perangkat lunak yang berbeda, di mana masing-masing memiliki peran dan tanggung jawab yang spesifik:

• Traffic Controller: Server pusat yang menangani logika bisnis inti, termasuk otentikasi, manajemen pengguna, dan orkestrasi data. Semua interaksi antar komponen lain dimediasi oleh Traffic Controller.
• Control Panel: Aplikasi yang diinstal pada perangkat Owner atau Officer. Perangkat lunak ini bertanggung jawab untuk otentikasi perangkat (Owner) dan otentikasi yang didelegasikan (Officer).
• Node API: Merupakan node penyimpanan yang aman dan terdesentralisasi yang dioperasikan oleh Owner. Node API menyimpan data sensitif, termasuk kredensial Officer, dan hanya dapat diakses melalui otorisasi dari Traffic Controller.
• Client Portal: Aplikasi yang digunakan oleh pengguna umum untuk berinteraksi dengan layanan yang disediakan, mengakses data dari Node API setelah melalui proses otentikasi yang diatur oleh Traffic Controller.

Penting untuk dipahami bahwa Control Panel, Node API, Traffic Controller, dan Client Portal bukanlah objek, melainkan domain perangkat lunak yang memiliki objek-objeknya sendiri.

Spesifikasi Perilaku & Alur Otentikasi

Berikut adalah skenario otentikasi yang menjadi dasar interaksi dalam sistem.

Skenario 1: Autentikasi Cross Subdomain (Owner)

Skenario ini menjelaskan alur otentikasi untuk Owner atau Notaris melalui Control Panel. Proses ini melibatkan verifikasi identitas pengguna dan identifikasi perangkat keras yang digunakan. Tujuannya adalah untuk memastikan setiap Owner hanya mengoperasikan satu node Safe pada satu perangkat.

Penjelasan Diagram: Diagram di atas menggambarkan alur otentikasi Control Panel untuk Owner. Control Panel mengirimkan kredensial dan hash perangkat ke Traffic Controller. Traffic Controller memvalidasi kredensial dan hash perangkat untuk kemudian mengeluarkan token dan status instalasi Safe.

Aktor

Owner/Notaris & Sistem

Rincian

Given seorang Owner membuka aplikasi Control Panel. When pengguna memasukkan username, password, dan Control Panel mengirimkannya beserta hash perangkat (jika ada). Then Traffic Controller memvalidasi kredensial. And jika password valid, Traffic Controller mencari data node/homesafe. And Traffic Controller mengirimkan token dalam set-cookie header dan payload berisi: hash, homesafe, dan safeinstall.

Skenario 2: Autentikasi Aplikasi Pengguna Umum

Skenario ini menjelaskan alur otentikasi untuk pengguna umum melalui Client Portal. Prosesnya lebih sederhana karena tidak memerlukan identifikasi perangkat.

Penjelasan Diagram: Diagram di atas menggambarkan alur otentikasi Client Portal untuk pengguna umum. Client Portal mengirimkan kredensial, Traffic Controller memvalidasinya, dan jika berhasil, Traffic Controller mengembalikan token sesi.

Aktor	Pengguna Umum & Sistem
Rincian	Given seorang pengguna umum membuka Client Portal. When pengguna memasukkan username dan password. Then Traffic Controller memvalidasi kredensial. And jika valid, Traffic Controller mengirimkan token otentikasi kembali ke Client Portal.

Skenario 3: Undangan dan Pendaftaran Officer

Skenario ini menjelaskan bagaimana seorang Owner mengundang Officer baru, yang kemudian mendaftar ke dalam sistem.

Penjelasan Diagram:

1. Owner membuat undangan melalui Control Panel, yang dikirim ke Traffic Controller.
2. Traffic Controller menghasilkan link unik dan memberikannya kembali ke Owner.
3. Officer menerima dan membuka link, yang mengarahkannya ke formulir pendaftaran.
4. Setelah Officer melengkapi formulir, data dikirim ke Traffic Controller, yang kemudian menyimpannya dan mengaitkannya dengan subdomain milik Owner.
5. Traffic Controller mengembalikan token sesi kepada Officer.
6. Traffic Controller kemudian mengirimkan data Officer (seperti kredensial) ke Node API yang relevan dalam bentuk JWT yang aman.

Aktor	Owner, Officer, & Sistem
Rincian	Given Owner ingin menambahkan Officer baru. When Owner mengirim undangan dari Control Panel. And Officer menerima link, mengisi formulir pendaftaran. Then Traffic Controller mendaftarkan Officer dan mengaitkannya dengan subdomain Owner. And Traffic Controller mengirimkan kredensial Officer ke Node API yang sesuai dalam bentuk JWT. And Traffic Controller memberikan token sesi kepada Officer.

Skenario 4: Autentikasi Officer (Delegated Authentication)

Skenario ini menjelaskan bagaimana Officer melakukan otentikasi. Karena kredensial Officer disimpan di Node API milik Owner, Traffic Controller harus mendelegasikan proses validasi ke Node API yang sesuai. Untuk memastikan keamanan, Traffic Controller tidak mengirimkan kredensial mentah, melainkan sebuah JWT yang ditandatanganinya.

Penjelasan Diagram:

1. Officer melakukan login melalui Control Panel.
2. Traffic Controller mengidentifikasi pengguna sebagai Officer dan mengambil subdomain terkait.
3. Traffic Controller membuat JWT yang berisi detail permintaan otentikasi, lalu mengirimkannya ke Node API yang sesuai dengan subdomain tersebut melalui endpoint /delegate-auth.
4. Node API memverifikasi tanda tangan JWT dan memvalidasi kredensial Officer secara lokal.
5. Node API mengembalikan hasil validasi (berhasil/gagal) ke Traffic Controller.
6. Jika berhasil, Traffic Controller menghasilkan token sesi dan mengirimkannya ke Control Panel Officer.

Aktor

Officer & Sistem

Rincian

Given Officer membuka Control Panel. When Officer memasukkan username dan password. Then Traffic Controller mengidentifikasi Officer dan subdomain terkait. And Traffic Controller mendelegasikan permintaan otentikasi ke Node API yang benar dengan mengirimkan JWT yang aman. And Node API memverifikasi JWT tersebut dan memvalidasi kredensial. And Traffic Controller menerima hasilnya dan memberikan token kepada Officer jika validasi berhasil.

Skenario 5: Otentikasi Berbasis JWT dan Rotasi Kunci

Karena jaringan ini dibentuk dengan arsitektur federated di atas protol HTTP, maka JWT dibutuhkan untuk autentikasi pengguna dalam sistem. Node API adalah sebutan untuk server terdistribusi, dan Traffic Controller adalah server pusatnya. Skenario ini menjelaskan bagaimana JWT digunakan dan bagaimana rotasi kunci asimetris untuk tanda tangan (signature) dikelola.

Skenario 5.1: Validasi cookie request yang diterima oleh Node API melalui middleware

1. Node API memeriksa apakah ada cookie pada request yang masuk.
2. Node API melakukan hashing pada keseluruhan nilai JWT.
3. Node API memeriksa keberadaan hash tersebut di dalam cache. Jika ditemukan, token dianggap valid, dan proses dilanjutkan ke langkah 7.
4. Jika hash tidak ada di cache, Node API melakukan decode pada JWT untuk mendapatkan kid (Key ID) dari header.
5. Node API mencari public_key yang sesuai dengan kid tersebut di dalam cache memori. Jika tidak ditemukan, Node API akan membuat request ke Traffic Controller untuk meminta public_key dengan versi yang dimaksud.
6. Setelah mendapatkan public_key, Node API memvalidasi tanda tangan JWT. Jika valid, Node API akan menyimpan hash dari JWT tersebut ke dalam cache untuk validasi di masa mendatang.
7. Jika token valid, permintaan akan diteruskan ke endpoint yang dituju pada server Node API.

Skenario 5.2: Validasi permintaan delegasi autentikasi (delegate-auth)

Proses validasi untuk permintaan delegate-auth mengikuti alur yang sama seperti pada Skenario 5.1, namun proses ini ditangani langsung oleh handler endpoint, bukan melalui middleware global.

Skenario 5.3: Validasi permintaan untuk menyimpan staff (store-officer)

(Alur validasi sama seperti pada Skenario 5.2, lihat diagram di atas)

Sama seperti delegate-auth, validasi untuk permintaan store-officer juga ditangani langsung oleh handler endpoint terkait dan mengikuti alur validasi JWT yang sama.

Skenario 5.4: Generasi kunci asimetris dan rotasi

Sistem menggunakan kunci asimetris untuk menandatangani JWT, memastikan integritas dan otentisitasnya. Untuk menjaga keamanan, kunci-kunci ini dirotasi secara berkala.

Format Versi Kunci: Versi kunci dicantumkan dalam kid (Key ID) header pada JWT dan mengikuti format berikut:

1. SESSION_KEY_xxx: Versi kunci yang digunakan untuk menandatangani token sesi autentikasi pengguna.
2. MATRIX_PROTOCOL_xxx: Versi kunci yang digunakan untuk menandatangani perintah-perintah yang dibuat oleh Traffic Controller untuk Node API (contoh: delegate-auth, store-officer). Hal ini memastikan hanya Traffic Controller yang dapat mengakses endpoint tersebut.

Pembuatan Kunci (Lazy Generation): Untuk efisiensi, semua kunci asimetris dalam sistem dibuat secara lazy (saat dibutuhkan pertama kali).

• Pasangan kunci SESSION_KEY baru akan dibuat jika belum ada saat proses autentikasi pengguna pertama kali terjadi setelah rotasi.
• Pasangan kunci MATRIX_PROTOCOL baru akan dibuat jika belum ada saat Traffic Controller perlu menandatangani perintah pertama kali ke Node API setelah rotasi.

Detail Teknis & Perancangan

Abstraksi & Objek Inti

Berikut adalah objek-objek data utama yang terlibat dalam alur otentikasi:

Objek	Anggota	Tipe Data/Keterangan
User	Properti:
	userId	string (ID unik pengguna)
	username	string
	passwordHash	string (Hash dari password, bisa null untuk Officer)
	userType	enum('owner', 'officer', 'general')
	subdomain	string (ID Notaris/Owner, untuk Officer)
Auth	Properti:
	username	string
	password	string (Password teks asli)
	hash	string (Hash identifikasi perangkat, opsional)
Token	Properti:
	jwt	string (JSON Web Token)
	payload	object (Data yang dikirim ke klien)
Node	Properti:
	nodeId	string (ID unik node/homesafe)
	ownerId	string (ID User pemilik)
	deviceHash	string (Hash perangkat yang terasosiasi)

Diagram Kelas (Class Diagram)

Diagram ini menunjukkan relasi antar objek-objek data inti dalam sistem.

Penjelasan Diagram: Diagram kelas di atas menunjukkan bahwa User dapat memiliki satu Node (khusus untuk Owner). Seorang User dengan tipe Owner dapat mengundang banyak User dengan tipe Officer.

ERD (Entity-Relationship Diagram)

Diagram ini merepresentasikan struktur database yang mendukung skenario otentikasi.

Penjelasan Diagram: ERD ini menunjukkan tabel USERS yang menyimpan data pengguna, termasuk user_type untuk membedakan peran. Kolom subdomain digunakan untuk mengaitkan Officer dengan Owner-nya. Tabel NODES menyimpan informasi tentang Node API yang dimiliki oleh Owner.

Rencana Pengujian (Test Cases)

Nama	Deskripsi	Hasil yang Diharapkan
Verifikasi Otentikasi Owner	Memastikan Control Panel dapat melakukan otentikasi Owner dengan hash perangkat.	Respons berisi token dan payload dengan status safeinstall dan homesafe yang benar.
Verifikasi Undangan Officer	Memastikan Owner dapat membuat link undangan dan Officer bisa mendaftar.	Officer berhasil dibuat di database dengan subdomain yang benar dan menerima token sesi.
Verifikasi Delegated Auth	Memastikan Officer dapat login melalui Traffic Controller yang mendelegasikan ke Node API.	Traffic Controller berhasil meneruskan permintaan ke Node API, dan Officer menerima token setelah Node API memvalidasi kredensial.